GitLab CI

GitLab CI is a continuous integration/deployment solution provided by the GitLab company. This document is a small tutorial on setting up a basic CI testing pipeline, and an introduction to the terminology.

Terminology

Job

A job is an ordered list of commands to execute. If any command exits with a non-zero exit code, execution halts and the job is marked as failed. An example job that will run in the testing stage:

test:
  stage: testing
  script:
    - echo "testing things!"

Any valid shell command is valid in a job, although you need to be careful with quotes and redirects. Shell variables can be set using the variables key:

test:
  stage: testing
  variables:
    FOO: bar
    BAR: foo
  script:
    - "echo ${FOO} > bar"

Jobs can also be tagged to run on certain branches:

test:
  stage: testing
  script:
    - echo "testing things!"
  only:
    - master

Build artifacts can be saved after a job runs. Artifacts are typically things like binary executables, job reports, or source tarballs. An example of saving artifacts:

test:
  stage: testing
  script:
    - "echo 'foobar' > out.txt"
  artifacts:
    paths:
      - out.txt

Artifacts from previous stages are available to all later stages.

Code coverage reports can also be tracked in GitLab, using a regular expression and the coverage key:

test:
  script:
    - cd build
    - ctest --output-on-failure
    - make coverage
  coverage: '/TOTAL\s*[0-9]+\s*[0-9]\s*([0-9]+\.[0-9]+%)/'

Stage

A stage is an unordered collection of jobs, declared at the top-level key stages:

stages:
  - build
  - test

The stages key is executed in order, synchronously.

Basic CI Pipeline

This is a basic CI pipeline for a project using CMake and the CLang compiler toolchain.

stages:
  - build
  - test

build:
  variables:
    LC_ALL: C.UTF-8
    LANG: C.UTF-8
    GIT_SUBMODULE_STRATEGY: recursive
    CXX: clang++
    CC: clang
  script:
    - mkdir build && cd build
    - cmake -D BUILD_COVERAGE=ON ..
    - make
  artifacts:
    paths:
      - build/

test:
  variables:
    LC_ALL: C.UTF-8
    LANG: C.UTF-8
    GIT_SUBMODULE_STRATEGY: recursive
  script:
    - cd build
    - ctest --output-on-failure
    - make coverage
  artifacts:
    paths:
      - build/
  coverage: '/TOTAL\s*[0-9]+\s*[0-9]\s*([0-9]+\.[0-9]+%)/'