GitLab CI/CD

tutorial

Job templates

In addition to the mender-ci-tools Docker image, Mender provides job templates for uploading Mender Artifacts and creating deployments to a group of devices.

The jobs use Personal Access Tokens feature which is only available in Mender Server version 3.4 or newer.

In this chapter we introduce the different jobs and provide examples on how to use them.

Upload a Mender Artifact job

.mender:upload:artifact job template uploads a Mender Artifact to a Mender Server.

Create a deployment job

.mender:create:deployment job template creates a deployment on a Mender server.

Setup

The job templates require the following CI variable to be set in the repository settings:

Make sure to protect the variable accordingly.

Pipelines examples

Build and deploy a Mender Artifact

#
# The example shows how to build, upload and deploy a Mender Artifact.
#
# 'MENDER_SERVER_ACCESS_TOKEN' secret is required to be set in GitLab repo settings
#

stages:
  - build
  - publish
  - deploy

include:
  - project: 'Northern.tech/Mender/mender-ci-workflows'
    file: 'templates/gitlab/mender-artifact-build.gitlab-ci.yml'
    ref: 'master'
  - project: 'Northern.tech/Mender/mender-ci-workflows'
    file: 'templates/gitlab/mender-artifact-upload.gitlab-ci.yml'
    ref: 'master'
  - project: 'Northern.tech/Mender/mender-ci-workflows'
    file: 'templates/gitlab/mender-deployment-create.gitlab-ci.yml'
    ref: 'master'

variables:
  MENDER_SERVER_URL: https://hosted.mender.io # Mender server URL
  MENDER_ARTIFACT_NAME: artifact.mender       # Mender Artifact file name in the `MENDER_ARTIFACTS_FOLDER` folder
  MENDER_RELEASE_NAME:  updated-auth_keys-1.0 # The name of Mender release

#
# Builds Mender artifact using 'mender-artifact' tool and upload it to MENDER_ARTIFACTS_FOLDER.
#
mender:build:artifact:
  stage: build
  extends: .mender:build:artifact
  script:
    # In this example, hello-mender.py represents a single file Python application that we have
    # built and test in our CI and now we want to deploy into a device running Mender. We will
    # package it as a Single File Application Update. For more information visit Mender docs:
    # https://docs.mender.io/artifact-creation/create-an-artifact
    - curl -O https://raw.githubusercontent.com/mendersoftware/mender-ci-workflows/master/examples/hello-mender.py
    - chmod 755 hello-mender.py
    - |
      single-file-artifact-gen \
        --device-type raspberrypi4 \
        -o ${MENDER_ARTIFACTS_FOLDER}/${MENDER_ARTIFACT_NAME} \
        -n ${MENDER_RELEASE_NAME} \
        --software-name hello-mender \
        --software-version 1.0 \
        --dest-dir /usr/local/bin \
        hello-mender.py

#
# Uploads Mender artifacts from MENDER_ARTIFACTS_FOLDER folder to a Mender server.
#
mender:upload:artifact:
  stage: publish
  extends: .mender:upload:artifact
  rules:
    - if: '$CI_COMMIT_BRANCH =~ "main"'

#
# Triggers a deployment on a group of devices.
#
mender:create:deployment:
  stage: deploy
  extends:
    - .mender:create:deployment
  rules:
    - if: '$CI_COMMIT_BRANCH =~ "main"'
  variables:
    MENDER_DEPLOYMENT_GROUP: group-dev # The name of Mender devices group a deployment will be triggered to
  before_script:
    - MENDER_DEPLOYMENT_NAME="app_${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA}" # `MENDER_DEPLOYMENT_NAME` variable defines the name of Mender deployment

Build and deploy multiple Mender Artifacts

#
# The example shows how to build, upload and deploy Mender Artifacts for two different 
# device types in paralel.
#
# 'MENDER_SERVER_ACCESS_TOKEN' secret is required to be set in GitLab repo settings
#

stages:
  - build
  - publish
  - deploy

include:
  - project: 'Northern.tech/Mender/mender-ci-workflows'
    file: 'templates/gitlab/mender-artifact-build.gitlab-ci.yml'
    ref: 'master'
  - project: 'Northern.tech/Mender/mender-ci-workflows'
    file: 'templates/gitlab/mender-artifact-upload.gitlab-ci.yml'
    ref: 'master'
  - project: 'Northern.tech/Mender/mender-ci-workflows'
    file: 'templates/gitlab/mender-deployment-create.gitlab-ci.yml'
    ref: 'master'

variables:
  MENDER_SERVER_URL: https://hosted.mender.io # Mender server URL
  MENDER_DEVICES_GROUP_NAME_ONE: group-one # The name of Mender devices group a deployment with Mender Artifact name `MENDER_ARTIFACT_NAME_ONE` will be triggered to
  MENDER_DEVICES_GROUP_NAME_TWO: group-two # The name of Mender devices group a deployment with Mender Artifact name `MENDER_ARTIFACT_NAME_TWO` will be triggered to
  MENDER_ARTIFACT_NAME_ONE: artifact_one.mender # First Mender Artifact file name in the `MENDER_ARTIFACTS_FOLDER` folder
  MENDER_ARTIFACT_NAME_TWO: artifact_two.mender # Second Mender Artifact file name in the `MENDER_ARTIFACTS_FOLDER` folder
  MENDER_RELEASE_NAME_ONE: auth_keys-1.0 # The name of Mender release for Mender Artifact name `MENDER_ARTIFACT_NAME_ONE`
  MENDER_RELEASE_NAME_TWO: some_config-1.0 # The name of Mender release for Mender Artifact name `MENDER_ARTIFACT_NAME_TWO`

#
# Builds Mender Artifacts using 'mender-artifact' tool
#
mender:build:artifact:one:
  stage: build
  extends: .mender:build:artifact
  script:
    - curl -O https://raw.githubusercontent.com/mendersoftware/mender-ci-workflows/master/examples/hello-mender.py
    - chmod 755 hello-mender.py
    - |
      single-file-artifact-gen \
        --device-type raspberrypi4 \
        -o ${MENDER_ARTIFACTS_FOLDER}/${MENDER_ARTIFACT_NAME_ONE} \
        -n ${MENDER_RELEASE_NAME_ONE} \
        --software-name hello-mender \
        --software-version 1.0 \
        --dest-dir /usr/local/bin \
        hello-mender.py

mender:build:artifact:two:
  stage: build
  extends: .mender:build:artifact
  script:
    # In this example, hello-mender.py represents a single file Python application that we have
    # built and test in our CI and now we want to deploy into a device running Mender. We will
    # package it as a Single File Application Update. For more information visit Mender docs:
    # https://docs.mender.io/artifact-creation/create-an-artifact
    - curl -O https://raw.githubusercontent.com/mendersoftware/mender-ci-workflows/master/examples/hello-mender.py
    - chmod 755 hello-mender.py
    - |
      single-file-artifact-gen \
        --device-type raspberrypi4 \
        -o ${MENDER_ARTIFACTS_FOLDER}/${MENDER_ARTIFACT_NAME_TWO} \
        -n ${MENDER_RELEASE_NAME_TWO} \
        --software-name hello-mender \
        --software-version 1.0 \
        --dest-dir /usr/local/bin \
        hello-mender.py

#
# Uploads built Mender Artifacts
#
mender:upload:artifact:one:
  stage: publish
  needs:
    - mender:build:artifact:one
  extends: .mender:upload:artifact
  rules:
    - if: '$CI_COMMIT_BRANCH =~ "main"'
  before_script:
    - MENDER_ARTIFACT_NAME=${MENDER_ARTIFACT_NAME_ONE} # `MENDER_ARTIFACT_NAME` variable defines first Mender Artifact file name in the `MENDER_ARTIFACTS_FOLDER` folder

mender:upload:artifact:two:
  stage: publish
  needs:
    - mender:build:artifact:two
  extends: .mender:upload:artifact
  rules:
    - if: '$CI_COMMIT_BRANCH =~ "main"'
  before_script:
    - MENDER_ARTIFACT_NAME=${MENDER_ARTIFACT_NAME_TWO} # `MENDER_ARTIFACT_NAME` variable defines second Mender Artifact file name in the `MENDER_ARTIFACTS_FOLDER` folder

#
# Creates deployments
#
mender:create:deployment:one:
  stage: deploy
  needs:
    - mender:upload:artifact:one
  extends:
    - .mender:create:deployment
  rules:
    - if: '$CI_COMMIT_BRANCH =~ "main"'
  before_script:
    - MENDER_DEPLOYMENT_GROUP=${MENDER_DEVICES_GROUP_NAME_ONE} # `MENDER_DEPLOYMENT_GROUP` variable defines the name of Mender devices group a deployment will be triggered to
    - MENDER_RELEASE_NAME=${MENDER_RELEASE_NAME_ONE} # `MENDER_RELEASE_NAME` variable defines the name of Mender release
    - MENDER_DEPLOYMENT_NAME="one_${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA}" # `MENDER_DEPLOYMENT_NAME` variable defines the name of Mender deployment

mender:create:deployment:two:
  stage: deploy
  needs:
    - mender:upload:artifact:two
  extends:
    - .mender:create:deployment
  rules:
    - if: '$CI_COMMIT_BRANCH =~ "main"'
  before_script:
    - MENDER_DEPLOYMENT_GROUP=${MENDER_DEVICES_GROUP_NAME_TWO} # `MENDER_DEPLOYMENT_GROUP` variable defines the name of Mender devices group a deployment will be triggered to
    - MENDER_RELEASE_NAME=${MENDER_RELEASE_NAME_TWO} # `MENDER_RELEASE_NAME` variable defines the name of Mender release
    - MENDER_DEPLOYMENT_NAME="two_${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA}" # `MENDER_DEPLOYMENT_NAME` variable defines the name of Mender deployment

Build and deploy a Mender Artifact to a single device

#
# The example shows how to deploy a Mender artifact to a single device.
#
# 'MENDER_SERVER_ACCESS_TOKEN' secret is required to be set in GitLab repo settings
#

stages:
  - build
  - publish
  - deploy

include:
  - project: 'Northern.tech/Mender/mender-ci-workflows'
    file: 'templates/gitlab/mender-artifact-build.gitlab-ci.yml'
    ref: 'master'
  - project: 'Northern.tech/Mender/mender-ci-workflows'
    file: 'templates/gitlab/mender-artifact-upload.gitlab-ci.yml'
    ref: 'master'
  - project: 'Northern.tech/Mender/mender-ci-workflows'
    file: 'templates/gitlab/mender-deployment-create.gitlab-ci.yml'
    ref: 'master'

variables:
  MENDER_SERVER_URL: https://hosted.mender.io # Mender server URL
  MENDER_ARTIFACT_NAME: artifact.mender       # Mender Artifact file name in the `MENDER_ARTIFACTS_FOLDER` folder
  MENDER_RELEASE_NAME:  auth_keys-1.0         # The name of Mender release

#
# Builds Mender demo single-file artifact and stores '.mender' binary
# to MENDER_ARTIFACTS_FOLDER folder
#
mender:build:artifact:
  stage: build
  extends: .mender:build:artifact
  script:
    # In this example, hello-mender.py represents a single file Python application that we have
    # built and test in our CI and now we want to deploy into a device running Mender. We will
    # package it as a Single File Application Update. For more information visit Mender docs:
    # https://docs.mender.io/artifact-creation/create-an-artifact
    - curl -O https://raw.githubusercontent.com/mendersoftware/mender-ci-workflows/master/examples/hello-mender.py
    - chmod 755 hello-mender.py
    - |
      single-file-artifact-gen \
        --device-type raspberrypi4 \
        -o ${MENDER_ARTIFACTS_FOLDER}/${MENDER_ARTIFACT_NAME} \
        -n ${MENDER_RELEASE_NAME} \
        --software-name hello-mender \
        --software-version 1.0 \
        --dest-dir /usr/local/bin \
        hello-mender.py

#
# Uploads built artifact ${MENDER_ARTIFACTS_FOLDER}/${MENDER_ARTIFACT_NAME} to
# Mender server on merge event to 'main' branch
#
mender:upload:artifact:
  stage: publish
  extends: .mender:upload:artifact
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

#
# Deploys to to a single device on merge event to 'main' branch
#
mender:create:deployment:
  stage: deploy
  extends: .mender:create:deployment
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  variables:
    MENDER_DEVICES_LIST: '["5ca6090ff3a8e90001206535"]' # `MENDER_DEVICES_LIST` variable defines list of Mender devices a deployment will be triggered to
  before_script:
    - MENDER_DEPLOYMENT_NAME="app_${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA}" # `MENDER_DEPLOYMENT_NAME` variable defines the name of Mender deployment

We welcome contributions to improve this documentation. To submit a change, use the Edit link at the top of the page or email us at .