…
|
||
---|---|---|
.. | ||
README.md |
Configuration of your builds with .gitlab-ci.yml
From version 7.12, GitLab CI uses a YAML
file (.gitlab-ci.yml
) for the project configuration. It is placed in the root
of your repository and contains definitions of how your project should be built.
The YAML file defines a set of jobs with constraints stating when they should
be run. The jobs are defined as top-level elements with a name and always have
to contain the script
clause:
job1:
script: "execute-script-for-job1"
job2:
script: "execute-script-for-job2"
The above example is the simplest possible CI configuration with two separate jobs, where each of the jobs executes a different command.
Of course a command can execute code directly (./configure;make;make install
)
or run a script (test.sh
) in the repository.
Jobs are used to create builds, which are then picked up by runners and executed within the environment of the runner. What is important, is that each job is run independently from each other.
.gitlab-ci.yml
The YAML syntax allows for using more complex job specifications than in the above example:
image: ruby:2.1
services:
- postgres
before_script:
- bundle_install
stages:
- build
- test
- deploy
job1:
stage: build
script:
- execute-script-for-job1
only:
- master
tags:
- docker
There are a few reserved keywords
that cannot be used as job names:
Keyword | Required | Description |
---|---|---|
image | no | Use docker image, covered in Use Docker |
services | no | Use docker services, covered in Use Docker |
stages | no | Define build stages |
types | no | Alias for stages |
before_script | no | Define commands that run before each job's script |
variables | no | Define build variables |
cache | no | Define list of files that should be cached between subsequent runs |
image and services
This allows to specify a custom Docker image and a list of services that can be used for time of the build. The configuration of this feature is covered in separate document: Use Docker.
before_script
before_script
is used to define the command that should be run before all
builds, including deploy builds. This can be an array or a multi-line string.
stages
stages
is used to define build stages that can be used by jobs.
The specification of stages
allows for having flexible multi stage pipelines.
The ordering of elements in stages
defines the ordering of builds' execution:
- Builds of the same stage are run in parallel.
- Builds of next stage are run after success.
Let's consider the following example, which defines 3 stages:
stages:
- build
- test
- deploy
- First all jobs of
build
are executed in parallel. - If all jobs of
build
succeeds, thetest
jobs are executed in parallel. - If all jobs of
test
succeeds, thedeploy
jobs are executed in parallel. - If all jobs of
deploy
succeeds, the commit is marked assuccess
. - If any of the previous jobs fails, the commit is marked as
failed
and no jobs of further stage are executed.
There are also two edge cases worth mentioning:
- If no
stages
is defined in.gitlab-ci.yml
, then by default thebuild
,test
anddeploy
are allowed to be used as job's stage by default. - If a job doesn't specify
stage
, the job is assigned thetest
stage.
types
Alias for stages.
variables
Note: Introduced in GitLab Runner v0.5.0.
GitLab CI allows you to add to .gitlab-ci.yml
variables that are set in build
environment. The variables are stored in the git repository and are meant to
store non-sensitive project configuration, for example:
variables:
DATABASE_URL: "postgres://postgres@postgres/my_database"
These variables can be later used in all executed commands and scripts.
The YAML-defined variables are also set to all created service containers, thus allowing to fine tune them.
cache
cache
is used to specify a list of files and directories which should be
cached between builds. Caches are stored according to the branch/ref and the
job name. They are not currently shared between different job names or between
branches/refs, which means that caching will benefit you if you push subsequent
commits to an existing feature branch.
If cache
is defined outside the scope of the jobs, it means it is set
globally and all jobs will use its definition.
To cache all git untracked files and files in binaries
:
cache:
untracked: true
paths:
- binaries/
Jobs
.gitlab-ci.yml
allows you to specify an unlimited number of jobs. Each job
must have a unique name, which is not one of the Keywords mentioned above.
A job is defined by a list of parameters that define the build behavior.
job_name:
script:
- rake spec
- coverage
stage: test
only:
- master
except:
- develop
tags:
- ruby
- postgres
allow_failure: true
Keyword | Required | Description |
---|---|---|
script | yes | Defines a shell script which is executed by runner |
stage | no (default: test ) |
Defines a build stage |
type | no | Alias for stage |
only | no | Defines a list of git refs for which build is created |
except | no | Defines a list of git refs for which build is not created |
tags | no | Defines a list of tags which are used to select runner |
allow_failure | no | Allow build to fail. Failed build doesn't contribute to commit status |
when | no | Define when to run build. Can be on_success , on_failure or always |
artifacts | no | Define list build artifacts |
cache | no | Define list of files that should be cached between subsequent runs |
script
script
is a shell script which is executed by the runner. For example:
job:
script: "bundle exec rspec"
This parameter can also contain several commands using an array:
job:
script:
- uname -a
- bundle exec rspec
stage
stage
allows to group build into different stages. Builds of the same stage
are executed in parallel
. For more info about the use of stage
please check
stages.
only and except
only
and except
are two parameters that set a refs policy to limit when
jobs are built:
only
defines the names of branches and tags for which the job will be built.except
defines the names of branches and tags for which the job will not be built.
There are a few rules that apply to the usage of refs policy:
only
andexcept
are inclusive. If bothonly
andexcept
are defined in a job specification, the ref is filtered byonly
andexcept
.only
andexcept
allow the use of regular expressions.only
andexcept
allow the use of special keywords:branches
andtags
.only
andexcept
allow to specify a repository path to filter jobs for forks.
In the example below, job
will run only for refs that start with issue-
,
whereas all branches will be skipped.
job:
# use regexp
only:
- /^issue-.*$/
# use special keyword
except:
- branches
The repository path can be used to have jobs executed only for the parent repository and not forks:
job:
only:
- branches@gitlab-org/gitlab-ce
except:
- master@gitlab-org/gitlab-ce
The above example will run job
for all branches on gitlab-org/gitlab-ce
,
except master.
tags
tags
is used to select specific runners from the list of all runners that are
allowed to run this project.
During the registration of a runner, you can specify the runner's tags, for
example ruby
, postgres
, development
.
tags
allow you to run builds with runners that have the specified tags
assigned to them:
job:
tags:
- ruby
- postgres
The specification above, will make sure that job
is built by a runner that
has both ruby
AND postgres
tags defined.
when
when
is used to implement jobs that are run in case of failure or despite the
failure.
when
can be set to one of the following values:
on_success
- execute build only when all builds from prior stages succeeded. This is the default.on_failure
- execute build only when at least one build from prior stages failed.always
- execute build despite the status of builds from prior stages.
For example:
stages:
- build
- cleanup_build
- test
- deploy
- cleanup
build_job:
stage: build
script:
- make build
cleanup_build_job:
stage: cleanup_build
script:
- cleanup build when failed
when: on_failure
test_job:
stage: test
script:
- make test
deploy_job:
stage: deploy
script:
- make deploy
cleanup_job:
stage: cleanup
script:
- cleanup after builds
when: always
The above script will:
- Execute
cleanup_build_job
only whenbuild_job
fails - Always execute
cleanup_job
as the last step in pipeline.
artifacts
Note: Introduced in GitLab Runner v0.7.0. Also, the Windows shell executor does not currently support artifact uploads.
artifacts
is used to specify list of files and directories which should be
attached to build after success. Below are some examples.
Send all files in binaries
and .config
:
artifacts:
paths:
- binaries/
- .config
Send all git untracked files:
artifacts:
untracked: true
Send all git untracked files and files in binaries
:
artifacts:
untracked: true
paths:
- binaries/
The artifacts will be send after a successful build success to GitLab, and will be accessible in the GitLab UI to download.
cache
Note: Introduced in GitLab Runner v0.7.0.
cache
is used to specify list of files and directories which should be cached
between builds. Below are some examples:
Cache all files in binaries
and .config
:
rspec:
script: test
cache:
paths:
- binaries/
- .config
Cache all git untracked files:
rspec:
script: test
cache:
untracked: true
Cache all git untracked files and files in binaries
:
rspec:
script: test
cache:
untracked: true
paths:
- binaries/
Locally defined cache overwrites globally defined options. This will cache only
binaries/
:
cache:
paths:
- my/files
rspec:
script: test
cache:
paths:
- binaries/
The cache is provided on best effort basis, so don't expect that cache will be always present. For implementation details please check GitLab Runner.
Validate the .gitlab-ci.yml
Each instance of GitLab CI has an embedded debug tool called Lint.
You can find the link under /ci/lint
of your gitlab instance.
Skipping builds
If your commit message contains [ci skip]
, the commit will be created but the
builds will be skipped.