Usage¶

How to create your own CI configuration¶

Here are the steps to follow in order to define your own custom build:

Create a branch in the Git repository to hold your customization
Write the CI configuration file (.gitlab-ci.yml)
Define optional trigger rules (.ci-trigger.yml)

Git repository branch¶

Our first step is to create, or locate, a branch where we will be hosting our CI configuration. Following the default and recommended naming conventions:

git clone https://gitlab.com/witekio/rnd/theembeddedkit/welma/ci.git
cd ci
git checkout --orphan config/username/main

CI configuration file¶

In our custom branch, we want to create the standard .gitlab-ci.yml file, holding the instructions for the CI:

${EDITOR} .gitlab-ci.yml
git add .gitlab-ci.yml
git commit
git push

Here is a template declaring and declining a standard Yocto BSP build for two machines:

.gitlab-ci.yml
stages:
  - "Build Yocto BSP"

.build-yocto:
  image: registry.gitlab.com/…/yocto:kirkstone
  script:
    - echo "Configure the container's environment…"
    - echo "Fetch the source code…"
    - . ./oe-init-build-env ${BUILD_DIR}
    - bitbake …
    - bitbake …
    - …
  variables:
    DISTRO: defaultsetup
    TEMPLATECONF: meta/conf/templates/default
    BUILD_DIR: build

"build:qemuarm64":
  extends: .build-yocto
  stage: "Build Yocto BSP"
  variables:
    MACHINE: qemuarm64

"build:qemuarm":
  extends: .build-yocto
  stage: "Build Yocto BSP"
  variables:
    MACHINE: qemuarm

Notes

For an explanation of the syntax, review the official GitLab documentation.
The .build-yocto entry will not be recognized as a CI job. It is thus used as a template to decline the build for qemuarm64 and qemuarm machines through the use of the extends keyword.
Entries under variables are exposed as environment variables thus saving us the need to manually export MACHINE, DISTRO, and TEMPLATECONF in the script section.
Jobs (i.e.: build:qemuarm64, and build:qemuarm) are independent from each other: they will run in parallel by default and not necessarily on the same machine.

CI configuration use case: Welma¶

For a Welma-specific build, we suggest to start from the main CI configuration branch of our config/projects-scarthgap release.From the .gitlab-ci.yml there, you will note…

… the inclusion of a `/snippet/welma.yml` file:¶

include:
  - project: ${CI_PROJECT_PATH}
    file: /snippets/welma.yml

This will include the content of the snippets/welma.yml file located in the default branch of this repository. It allows us to create reusable defaults for building Yocto images and running CVE Scan analyses and tests.

In /snippet/welma.yml, you will note…

… the inclusion of a `/snippet/common.yml` file:¶

include:
  - /snippets/common.yml

This will include the content of the snippets/common.yml file. It allows us to create reusable defaults for most operations. Currently, you will find various helpers (.snippets) to setup Git and OpenSSH for the container environment in the CI environment.

Those helpers are currently used as part of the scripting of jobs, referenced by using the !reference […] tag.

You can also read more about the include keyword in the official documentation.

… the tagging of the jobs to specific runners:¶

tags:
  - has:shared-folder
  - usage:yocto

This ensures that the jobs run on our special runners, where we configured a shared folder between runners, for build-time optimization purposes.

The variables are set to use the shared folder.

We use the standard DL_DIR and SSTATE_DIR configuration variables to set a custom location for the downloads and sstate folders of bitbake. These are defined in the snippets/variables.yml file:

variables:
  ...
  SSTATE_DIR: /share/sstate
  DL_DIR: /share/downloads

Trigger rules¶

In our custom branch, we can also create a custom .ci-trigger.yml file, holding a limited subset of GitLab CI definitions, to condition the scheduling of this branch for automatic building.

${EDITOR} .ci-trigger.yml
git add .ci-trigger.yml
git commit
git push

About the default behavior without trigger rules:

Not providing a trigger rules file will make this CI configuration branch always execute upon trigger from an external repository.

We do not recommend this practice as it may waste resources since the change which triggered the build may be related to code unused in your custom build.

This file should contain a rules keyword definition:

rules:
  - …

An example can be found in our config/projects-scarthgap branch:

rules:
  - if: $CI_PROJECT_PATH =~ /.*\/meta-welma/ && $CI_COMMIT_BRANCH == "kirkstone-next"

Upon trigger of the CI from an external repository, if the event comes from a repository named meta-welma and in the kirkstone-next branch, then schedule the build of this configuration branch. This ensures that the build configuration in our config/projects-scarthgap branch matches changes made into meta-welma in the kirkstone-next branch.

How to trigger builds¶

Here are the few ways the pipeline described in your CI configuration can be triggered:

Automatically, through our custom trigger system.
Manually through the GitLab UI in a repository implementing our trigger system (e.g. from meta-welma), from the sidebar: Build -> Pipelines -> Run Pipeline and select your Git branch before pushing the Run Pipeline button.
Manually through the GitLab UI, from the sidebar: Build -> Pipelines -> Run Pipeline and select your Git branch before pushing the Run Pipeline button.
Manually through the glab CLI: glab ci run --branch <name>.
Manually, using the Pipeline API.