Pipeline Config

Pipeline parameters

stages

Required

The pipeline configuration begins with the definition of stages. A stage is a string that describes a group of jobs as a step of a software life-cycle.

Example
stages:
    - test
    - build
    - deploy

image

Default value: alpine

A default docker image that should be used for creating the job container. The image will be pulled automatically if doesn’t present in the system.

This value will be used if a job doesn’t define its own image property.

The value may contain environment variables that will be expanded during the job execution.

Example
stages:
    - test
    - build

image: "maven:3"

variables

A dictionary of key-value dynamically-named values passed as environment variables to job’s commands.

  • Overrides variables specified on repository/project level.
Example
stages:
    - test
    - build

image: "maven:3"

variables:
    JAVA_OPTS: "-Xms512m -Xmx1024m"

Job parameters

The heart of the pipeline is a job.

A job is defined as a list of parameters that specify the way job executed. Each job has the stage and commands parameters defining in which stage it will be executed and the job’s behavior.

The job name is specified as a key of the YAML top element. The job name must be unique. The job name should not start with a dot, otherwise, the job will not be started as it will be considered hidden.

stage

Required

stage is a string that defines which stage the job belongs to.

Example
unit tests:
    stage: test

commands

Required

A list of commands to be executed by the runner in an isolated container created from the given Docker image (specified as image). Each command must complete successfully, otherwise, other commands will not be executed, and the job will fail.

Example
build js:
    stage: build
    commands:
        - npm install
        - npm run-script build

image

Default value: alpine

A docker image that should be used for creating the job container. The image will be pulled automatically if doesn’t present in the system.

The value can contain environment variables that will be expanded during the job execution.

Example

unit tests:
    image: golang
unit tests:
    image: "maven:3"

variables

A dictionary of key-value dynamically-named values passed as environment variables to job’s commands.

  • Overrides variables specified on repository/project level.
  • Overrides variables specified on pipeline level.
Example
unit tests:
    stage: test
    variables:
        JAVA_OPTS: "-Xms512m -Xmx1024m"
demo:
    stage: test
    variables:
        TARGET: "World"
    commands:
        - echo Hello $TARGET

only

The only property is optional and defines a list of conditions, which are based on a branch name or a tag name, which triggered pipeline, or on an environment variable name. If these conditions are not fulfilled, the job will be skipped in the pipeline.

There are several filters: branches, tags and variables.

The job will be executed only if the following conditions are fulfilled:

  • if branches field is not empty and it includes Git branch name that triggered the pipeline

OR

  • if tags field is not empty and it includes Git tag name that triggered the pipeline

AND

  • if variables field is not empty and it matches at least one variable name which was specified on project, repository levels or in New Pipeline dialog.

If no branches, tags and variables specified, then the expression is not applied to the job and it will be executed.

If the conditions are not fulfilled, the job will not be executed.

only: branches

A list of branch names that are allowed to execute the given job.

Branch names are matched using either exact match or regular expression match.

Example

The job deploy to production will be executed only on master branch, while the job run tests will be executed on any branch/tag.

stages:
    - test
    - deploy

run tests:
    stage: test
    commands:
        - npm test

deploy to production:
    stage: deploy
    only:
        branches:
            - master
    commands:
        - kubectl apply -f deployment.yaml

only: tags

A list of tag names that are allowed to execute the given job.

Tag names are matched using either exact match or regular expression match.

Example

The job deploy to staging will be executed only on staging branch or on tag deploy-staging, while the job run build will be executed on any branch/tag.

stages:
    - build
    - deploy

run build:
    stage: build
    commands:
        - npm run-script build

deploy to staging:
    stage: deploy
    only:
        branches:
            - staging
        tags:
            - deploy-staging
    commands:
        - kubectl apply -f deployment.yaml

only: variables

A list of variables, at least one of them is required to be passed for creating & executing the job.

The following variables are evaluated:

  • environment variables specified on the project level (Project → Settings → Variables);
  • environment variables specified on the repository level (Repository → Settings → Variables);
  • variables specified in global variables: section of the pipeline config;
  • variables specified in variables: section of the job;
  • variables specified by the user in the New Pipeline dialog.

Note, that variable name must be prefixed with $ unless the regular expression syntax is used.

Example

The job deploy to staging will be executed only when a user specified staging variable through the New Pipeline dialog or specified it in Project/Repository variables.

stages:
    - build
    - deploy

run build:
    stage: build
    commands:
        - npm run-script build

deploy to staging:
    stage: deploy
    only:
        variables:
            - $staging
    commands:
        - kubectl apply -f deployment.yaml

only: using regular expressions

In addition to the exact match syntax described in the previous sections, branch, tag, and variable conditions can be specified using a regular expression.

A regular expression must be surrounded by the / character, like this: /deploy_(staging|production)/ (matches both deploy_staging and deploy_production).

Snake CI uses the Java regular expression syntax.

Example

The job run full test suite (slow) executes for any branch which name starts with feature-, for example, feature-new-ui.

But if triggering branch name starts with hotfix-, then only run core test suite (fast) job executes.

stages:
    - deploy

run full test suite (slow):
    stage: deploy
    only:
        branches:
            - /^feature-/
    commands:
        - gradle test

run core test suite (fast):
    stage: deploy
    only:
        branches:
            - /^hotfix-/
    commands:
        - gradle test --tests '*CoreTest*'

Tips & Tricks

You can introduce a hidden job by starting its name with . (dot) and then assign it to an anchor and merge it in other jobs in order to avoid duplication.

image: alpine

variables:
    GO111MODULES: "off"

stages:
    - "build"

.build: &parent_build
    stage: build
    commands:
        - go build

build for mac:
    <<: *parent_build
    variables:
        GOOS: "darwin"

build for linux:
    <<: *parent_build
    variables:
        GOOS: "linux"

Read more about YAML merge in the official doc


Last modified July 1, 2020