Show Menu
Cheatography

GitLab CI/CD Pipeline Configuration Cheat Sheet (DRAFT) by

GitLab CI/CD Pipeline Configuration YAML Examples

This is a draft cheat sheet. It is a work in progress and is not finished yet.

Pipeline Archit­ecture

Globals | Includes | Before­/After | Extends

Global Defaults

default
image | services | before­_script | after_­script | cache
variables
Cannot be specified under default
stages
Cannot be specified under default
Job values always override global defaults.

Include

include:
  - remote: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
  - local: '/templates/.after-script-template.yml'
  - template: Auto-DevOps.gitlab-ci.yml
  - project: 'my-group/my-project'
    ref: master
    file: '/templates/.gitlab-ci-template.yml'
extension: .yml | .yaml

Before and After Scripts

default:
  before_script:
    - global before script

job:
  before_script:
    - execute this instead of global version
  script:
    - my command
  after_script:
    - execute this after my script

Extends

.only-important:
  only:
    - master
    - stable
  tags:
    - production

.in-docker:
  tags:
    - docker
  image: alpine

rspec:
  extends:
    - .only-important
    - .in-docker
  script:
    - rake rspec

spinach:
  extends: .in-docker
  script: rake spinach
 

Jobs Management

Stages | Parameters | Enviro­nments

Stages

stages:
  - .pre
  - build
  - test
  - deploy
  - .post
.pre and .post stages are guaranteed to be the first (.pre) or last (.post) stage in a pipeline

Disabling Jobs by Hiding Them

.hidden_job:
  script:
    - run test
tempor­arily ‘disable’ a job by prepending a dot (.)

Variables

variables:
  ENVIRONMENT: "staging"
  DB_URL: "postgres://postgres@postgres/db

build:
  script: mvn build
  variables:
    ENVIRONMENT: "production"

Enviro­nment

review_app:
  stage: deploy
  script: make deploy-app
  environment:
    name: review
    on_stop: stop_review_app

stop_review_app:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script: make delete-app
  when: manual
  environment:
    name: review
    action: stop

deploy as review app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com/

Pages

pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  only:
    - master
Pages is a special job that is used to upload static content to GitLab that can be used to serve your website

Parallel

test:
  parallel: 3
  script:
    - bundle
    - bundle exec rspec_booster --job $CI_NODE_INDEX/$CI_NODE_TOTAL
parallel allows you to configure how many instances of a job to run in parallel. This value has to be greater than or equal to two (2) and less than or equal to 50.

Trigger

staging:
  stage: deploy
  trigger: my/deployment

staging-branch:
  stage: deploy
  trigger:
    project: my/deployment
    branch: stable
trigger allows you to define downstream pipeline trigger. When a job created from trigger definition is started by GitLab, a downstream pipeline gets created.

Tags

job:
  tags:
    - ruby
    - postgres

osx job:
  stage:
    - build
  tags:
    - osx
  script:
    - echo "Hello, $USER!"
tags is used to select specific Runners from the list of all Runners that are allowed to run this project. During the regist­ration of a Runner, you can specify the Runner’s tags, for example ruby, postgres, windows, osx.

Needs

linux:build:
  stage: build

mac:build:
  stage: build

linux:rspec:
  stage: test
  needs: ["linux:build"]

linux:rubocop:
  stage: test
  needs: ["linux:build"]

mac:rspec:
  stage: test
  needs: ["mac:build"]

mac:rubocop:
  stage: test
  needs: ["mac:build"]

production:
  stage: deploy
The needs: keyword enables executing jobs out-of­-order, allowing you to implement a directed acyclic graph. This lets you run some jobs without waiting for other ones, disreg­arding stage ordering so you can have multiple stages running concur­rently.

Depend­encies

build:osx:
  stage: build
  script: make build:osx
  artifacts:
    paths:
      - binaries/

build:linux:
  stage: build
  script: make build:linux
  artifacts:
    paths:
      - binaries/

test:osx:
  stage: test
  script: make test:osx
  dependencies:
    - build:osx

test:linux:
  stage: test
  script: make test:linux
  dependencies:
    - build:linux

deploy:
  stage: deploy
  script: make deploy
By default, all artifacts from all previous stages are passed to the current job, but you can use the depend­encies parameter to define a limited list of jobs (or no jobs) to fetch artifacts from.
 

Flow Control

Rules | Retries

rules Evaluation

docker build:
  script: docker build -t my-image:$SLUG .
  rules:
    - changes:
      - Dockerfile
      when: manual
    - if: '$VAR == "string value"'
      when: manual 
    - when: on_success

docker build:
  script: docker build -t my-image:$SLUG .
  rules:
    - if: '$VAR == "string value"'
      changes:
      - Dockerfile
      - docker/scripts/*
      when: manual
To conjoin if and changes clauses with an AND, use them in the same rule.

Job Retries

test:
  script: rspec
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
when: always | unknow­n_f­ailure | script­_fa­ilure | api_fa­ilure | stuck_­or_­tim­eou­t_f­ailure | runner­_sy­ste­m_f­ailure | missin­g_d­epe­nde­ncy­_fa­ilure | runner­_un­sup­ported

Interr­uptible

stages:
  - stage1
  - stage2

step-1:
  stage: stage1
  script:
    - echo "Can be canceled"
  
step-2:
  stage: stage2
  script:
    - echo "Can not be canceled"
  interruptible: false
This value will only be used if the automatic cancel­lation of redundant pipelines feature is enabled.

Protecting Manual Jobs

deploy_prod:
  stage: deploy
  script:
    - echo "Deploy to production server"
  environment:
    name: production
    url: https://example.com
  when: manual
  only:
    - master
  allow_failure: false
In the protected enviro­nments settings, select the enviro­nment and add the users, roles or groups that are authorized to trigger the manual job to the Allowed to Deploy list

Artifact Management

Artifacts | Docker | Cache

Artifacts

job:
  artifacts:
    name: "$CI_JOB_NAME"
    paths:
      - binaries/
      - .config
    untracked: true
    when: on_failure
    expire_in: 1 week

code_quality:
  stage: test
  script: codequality /code
  artifacts:
    reports:
      codequality: gl-code-quality-report.json
  coverage: '/Code coverage: \d+\.\d+/'
untracked: true | false when: on_success | on_failure | always | manual

Docker Image

image:
  name: super/sql:experimental
  entrypoint: [""]

Docker Service

services:
  - name: postgres:9.4
    alias: db
    entrypoint: ["docker-entrypoint.sh"]
    command: ["postgres"]

Cache

build:
  script: mvn test
  cache:
    key: build
    untracked: true
    paths:
      - binaries/
    policy: pull
policy : pull | push | pull-push untracked : true | false