gitlab 添加https://gitlab.com/ci gitlab-ci-multi-runner

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, the

test

jobs
are executed in parallel.
If all jobs of

test

succeeds, the

deploy

jobs
are executed in parallel.
If all jobs of

deploy

succeeds, the commit is marked as

success

.
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 the

build

,

test

and

deploy

are
allowed to be used as job's stage by default.
If a job doesn't specify

stage

, the job is assigned the

test

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

Note: Introduced in GitLab Runner v0.7.0.

cache

is used to specify a list of files and directories which should be cached between builds.

By default the caching is enabled per-job and per-branch.

If

cache

is defined outside the scope of the jobs, it means it is set globally and all jobs will use its definition.

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.

cache:key

Note: Introduced in GitLab Runner v1.0.0.

The

key

directive allows you to define the affinity of caching between jobs, allowing to have a single cache for all jobs, cache
per-job, cache per-branch or any other way you deem proper.

This allows you to fine tune caching, allowing you to cache data between different jobs or even different branches.

The

cache:key

variable can use any of the predefined
variables.

Example configurations

To enable per-job caching:

cache:
key: "$CI_BUILD_NAME"
untracked: true

To enable per-branch caching:

cache:
key: "$CI_BUILD_REF_NAME"
untracked: true

To enable per-job and per-branch caching:

cache:
key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME"
untracked: true

To enable per-branch and per-stage caching:

cache:
key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME"
untracked: true

If you use Windows Batch to run your shell scripts you need to replace

$

with

%

:

cache:
key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%"
untracked: true

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
image	no	Use docker image, covered in Using Docker Images
services	no	Use docker services, covered in Using Docker Images
stage	no	Defines a build stage (default: test )
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
dependencies	no	Define other builds that a build depends on so that you can pass artifacts between them
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

and

except

are
inclusive. If both

only

and

except

are
defined in a job specification, the ref is filtered by

only

and

except

.

only

and

except

allow
the use of regular expressions.

only

and

except

allow
the use of special keywords:

branches

,

tags

,
and

triggers

.

only

and

except

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

In this example,

job

will run only for refs that are tagged, or if a build is explicitly requested via an API trigger.

job:
# use special keywords
only:
- tags
- triggers

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 when

build_job

fails
Always execute

cleanup_job

as the last step in pipeline.

artifacts

Notes:

Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
Windows support was added in GitLab Runner v.1.0.0.
Currently not all executors are supported.
Build artifacts are only collected for successful builds.

artifacts

is used to specify list of files and directories which should be attached to build after success. To pass artifacts between
different builds, see dependencies.

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/

You may want to create artifacts only for tagged releases to avoid filling the build server storage with temporary build artifacts.

Create artifacts only for tags (

default-job

will not create artifacts):

default-job:
script:
- mvn test -U
except:
- tags

release-job:
script:
- mvn package -U
artifacts:
paths:
- target/*.war
only:
- tags

The artifacts will be sent to GitLab after a successful build and will be available for download in the GitLab UI.

artifacts:name

Note: Introduced in GitLab 8.6 and GitLab Runner v1.1.0.

The

name

directive allows you to define the name of the created artifacts archive. That way, you can have a unique name of every
archive which could be useful when you'd like to download the archive from GitLab. The

artifacts:name

variable can make use of
any of the predefined variables.

Example configurations

To create an archive with a name of the current build:

job:
artifacts:
name: "$CI_BUILD_NAME"

To create an archive with a name of the current branch or tag including only the files that are untracked by Git:

job:
artifacts:
name: "$CI_BUILD_REF_NAME"
untracked: true

To create an archive with a name of the current build and the current branch or tag including only the files that are untracked by Git:

job:
artifacts:
name: "${CI_BUILD_NAME}_${CI_BUILD_REF_NAME}"
untracked: true

To create an archive with a name of the current stage and branch name:

job:
artifacts:
name: "${CI_BUILD_STAGE}_${CI_BUILD_REF_NAME}"
untracked: true

If you use Windows Batch to run your shell scripts you need to replace

$

with

%

:

job:
artifacts:
name: "%CI_BUILD_STAGE%_%CI_BUILD_REF_NAME%"
untracked: true

dependencies

Note: Introduced in GitLab 8.6 and GitLab Runner v1.1.1.

This feature should be used in conjunction with

artifacts

and
allows you to define the artifacts to pass between different builds.

Note that

artifacts

from previous stages are
passed by default.

To use this feature, define

dependencies

in context of the job and pass a list of all previous builds from which the artifacts
should be downloaded. You can only define builds from stages that are executed before the current one. An error will be shown if you define builds from the current stage or next ones.

In the following example, we define two jobs with artifacts,

build:osx

and

build:linux

.
When the

test:osx

is executed, the artifacts from

build:osx

will
be downloaded and extracted in the context of the build. The same happens for

test:linux

and artifacts from

build:linux

.

The job

deploy

will download artifacts from all previous builds because of the stage precedence:

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

Hidden jobs

Note: Introduced in GitLab 8.6 and GitLab Runner v1.1.1.

Jobs that start with a dot (

.

) will be not processed by GitLab CI. You can use this feature to ignore jobs, or use the special
YAML features and transform the hidden jobs into templates.

In the following example,

.job_name

will be ignored:

.job_name:
script:
- rake spec

Special YAML features

It's possible to use special YAML features like anchors (

&

), aliases (

*

)
and map merging (

<<

), which will allow you to greatly reduce the complexity of

.gitlab-ci.yml

.

Read more about the various YAML features.

Anchors

Note: Introduced in GitLab 8.6 and GitLab Runner v1.1.1.

YAML also has a handy feature called 'anchors', which let you easily duplicate content across your document. Anchors can be used to duplicate/inherit properties, and is a perfect example to be used with hidden
jobs to provide templates for your jobs.

The following example uses anchors and map merging. It will create two jobs,

test1

and

test2

,
that will inherit the parameters of

.job_template

, each having their own custom

script

defined:

.job_template: &job_definition  # Hidden job that defines an anchor named 'job_definition'
image: ruby:2.1
services:
- postgres
- redis

test1:
<<: *job_definition           # Merge the contents of the 'job_definition' alias
script:
- test1 project

test2:
<<: *job_definition           # Merge the contents of the 'job_definition' alias
script:
- test2 project

&

sets up the name of the anchor (

job_definition

),

<<

means
"merge the given hash into the current one", and

*

includes the named anchor (

job_definition

again).
The expanded version looks like this:

.job_template:
image: ruby:2.1
services:
- postgres
- redis

test1:
image: ruby:2.1
services:
- postgres
- redis
script:
- test1 project

test2:
image: ruby:2.1
services:
- postgres
- redis
script:
- test2 project

Let's see another one example. This time we will use anchors to define two sets of services. This will create two jobs,

test:postgres

and

test:mysql

,
that will share the

script

directive defined in

.job_template

,
and the

services

directive defined in

.postgres_services

and

.mysql_services

respectively:

.job_template: &job_definition
script:
- test project

.postgres_services:
services: &postgres_definition
- postgres
- ruby

.mysql_services:
services: &mysql_definition
- mysql
- ruby

test:postgres:
<< *job_definition
services: *postgres_definition

test:mysql:
<< *job_definition
services: *mysql_definition

The expanded version looks like this:

.job_template:
script:
- test project

.postgres_services:
services:
- postgres
- ruby

.mysql_services:
services:
- mysql
- ruby

test:postgres:
script:
- test project
services:
- postgres
- ruby

test:mysql:
script:
- test project
services:
- mysql
- ruby

You can see that the hidden jobs are conveniently used as templates.

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.

Examples

Visit the examples README to see a list of examples using GitLab CI with various languages.
http://doc.gitlab.com/ce/ci/yaml/README.html
Currently we support Debian, Ubuntu and CentOS.

If you want to use Docker runner, install it before using the multi runner:

curl -sSL https://get.docker.com/ | sh

Add GitLab's official repository via apt-get or yum:

# For Debian/Ubuntu
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.deb.sh | sudo bash

# For CentOS
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.rpm.sh | sudo bash

Install

gitlab-ci-multi-runner

:

# For Debian/Ubuntu
sudo apt-get install gitlab-ci-multi-runner

# For CentOS
sudo yum install gitlab-ci-multi-runner

Register the runner:

sudo gitlab-ci-multi-runner register

Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/ci ) https://gitlab.com/ci Please enter the gitlab-ci token for this runner
xxx
Please enter the gitlab-ci description for this runner
my-runner
INFO[0034] fcf5c619 Registering runner... succeeded
Please enter the executor: shell, docker, docker-ssh, ssh?
docker
Please enter the Docker image (eg. ruby:2.1):
ruby:2.1
INFO[0037] Runner registered successfully. Feel free to start it, but if it's
running already the config should be automatically reloaded!

The runner should be started already and you are ready to build your projects!

Make sure that you read the FAQ section which
describes some of the most common problems with GitLab Runner.

Update

Simply execute to install latest version:

# For Debian/Ubuntu
sudo apt-get update
sudo apt-get install gitlab-ci-multi-runner

# For CentOS
sudo yum update
sudo yum install gitlab-ci-multi-runner

GitLab Runner Commands

GitLab Runner contains a set of commands with which you register, manage and run your builds.

You can check a recent list of commands by executing:

gitlab-runner --help

Append

--help

after
a command to see its specific help page:

gitlab-runner <command> --help

Table of Contents generated with DocToc

Using
environment variables
Running
in debug mode
Super-user
permission
Configuration
file
Signals
Commands
overview
Registration-related
commands

gitlab-runner register

Interactive
registration
Non-interactive
registration

gitlab-runner list
gitlab-runner
verify
gitlab-runner
unregister

Service-related
commands

gitlab-runner
install
gitlab-runner
uninstall
gitlab-runner
start
gitlab-runner
stop
gitlab-runner
restart
gitlab-runner
status
Multiple
services

Run-related
commands

gitlab-runner
run
gitlab-runner
run-single
gitlab-runner exec
Limitations
of

gitlab-runner
exec

Internal
commands

gitlab-runner
artifacts-downloader
gitlab-runner
artifacts-uploader
gitlab-runner
cache-archiver
gitlab-runner
cache-extractor

Troubleshooting

Access
Denied when running the service-related commands

Using
environment variables

Most of the commands support environment variables as a method to pass the configuration to the command.

You can see the name of the environment variable when invoking

--help

for
a specific command. For example, you can see below the help message for the

run

command:

gitlab-runner run --help

The output would be similar to:

NAME:
gitlab-runner run - run multi runner service

USAGE:
gitlab-runner run [command options] [arguments...]

OPTIONS:
-c, --config "/Users/ayufan/.gitlab-runner/config.toml"  Config file [$CONFIG_FILE]

Running
in debug mode

Debug mode is especially useful when looking for the cause of some undefined behavior or error.

To run a command in debug mode, prepend the command with

--debug

:

gitlab-runner --debug <command>

Super-user
permission

Commands that access the configuration of GitLab Runner behave differently when executed as super-user (

root

).
The file location depends on the user executing the command.

Be aware of the notice that is written when executing the commands that are used for running builds, registering services or managing registered runners:

gitlab-runner run

INFO[0000] Starting multi-runner from /Users/ayufan/.gitlab-runner/config.toml ...  builds=0
WARN[0000] Running in user-mode.
WARN[0000] Use sudo for system-mode:
WARN[0000] $ sudo gitlab-runner...

You should use

user-mode

if
you are really sure that this is a mode that you want to work with. Otherwise, prefix your command with

sudo

:

sudo gitlab-runner run

INFO[0000] Starting multi-runner from /etc/gitlab-runner/config.toml ...  builds=0
INFO[0000] Running in system-mode.

In the case of Windows you may need to run the Command Prompt in Administrative Mode.

Configuration
file

GitLab Runner configuration uses the TOML format.

The file to be edited can be found in:

/etc/gitlab-runner/config.toml

on
*nix systems when gitlab-runner is executed as super-user (

root

)

~/.gitlab-runner/config.toml

on
*nix systems when gitlab-runner is executed as non-root

./config.toml

on
other systems

Most of the commands accept an argument to specify a custom configuration file, allowing you to have a multiple different configurations on a single machine. To specify a custom configuration file use the

-c

or

--config

flag,
or use the

CONFIG_FILE

environment
variable.

Signals

It is possible to use system signals to interact with GitLab Runner. The following commands support the following signals:

Command	Signal	Action
register	SIGINT	Cancel runner registration and delete if it was already registered
run , exec , run-single	SIGINT,SIGTERM	Abort all running builds and exit as soon as possible. Use twice to exit now (forceful shutdown).
run , exec , run-single	SIGQUIT	Stop accepting a new builds. Exit as soon as currently running builds do finish (graceful shutdown).
run	SIGHUP	Force to reload configuration file

Commands
overview

This is what you see if you run

gitlab-runner

without
any arguments:

NAME:
gitlab-runner - a GitLab Runner

USAGE:
gitlab-runner [global options] command [command options] [arguments...]

VERSION:
1.0.0~beta.142.ga8d37f3 (a8d37f3)

AUTHOR(S):
Kamil Trzciński <ayufan@ayufan.eu>

COMMANDS:
exec     execute a build locally
run      run multi runner service
register register a new runner
install  install service
uninstall    uninstall service
start    start service
stop     stop service
restart  restart service
status   get status of a service
run-single   start single runner
unregister   unregister specific runner
verify   verify all registered runners
archive  find and archive files (internal)
artifacts    upload build artifacts (internal)
extract  extract files from an archive (internal)
help, h  Shows a list of commands or help for one command

Below we will explain what each command does in detail.

Registration-related
commands

The following commands allow you to register a new runner, or list and verify them if they are still registered.

gitlab-runner register

Interactive
registration
Non-interactive
registration

gitlab-runner list
gitlab-runner
verify
gitlab-runner
unregister

The above commands support the following arguments:

Parameter	Default	Description
--config	See the configuration file section	Specify a custom configuration file to be used

gitlab-runner register

This command registers your GitLab Runner in GitLab. The registered runner is added to the configuration
file. You can use multiple configurations in a single GitLab Runner. Executing

gitlab-runner
register

adds a new configuration entry, it doesn't remove the previous ones.

There are two options to register a Runner, interactive and non-interactive.

Interactive
registration

This command is usually used in interactive mode (default). You will be asked multiple questions during a Runner's registration.

This question can be pre-filled by adding arguments when invoking the registration command:

gitlab-runner register --name my-runner --url http://gitlab.example.com --registration-token my-registration-token

Or by configuring the environment variable before the

register

command:

export CI_SERVER_URL=http://gitlab.example.com
export RUNNER_NAME=my-runner
export REGISTRATION_TOKEN=my-registration-token
export REGISTER_NON_INTERACTIVE=true
gitlab-runner register

To check all possible arguments and environments execute:

gitlab-runner register --help

Non-interactive
registration

It's possible to use registration in non-interactive / unattended mode.

You can specify the arguments when invoking the registration command:

gitlab-runner register --non-interactive <other-arguments>

Or by configuring the environment variable before the

register

command:

<other-environment-variables>
export REGISTER_NON_INTERACTIVE=true
gitlab-runner register

gitlab-runner list

This command lists all runners saved in the configuration
file.

gitlab-runner
verify

This command checks if the registered runners can connect to GitLab, but it doesn't verify if the runners are being used by the GitLab Runner service. An example output is:

Verifying runner... is alive                        runner=fee9938e
Verifying runner... is alive                        runner=0db52b31
Verifying runner... is alive                        runner=826f687f
Verifying runner... is alive                        runner=32773c0f

To delete the old and removed from GitLab runners, execute the following command.

Warning: This operation cannot be undone, it will update the configuration file, so make sure to have a backup of

config.toml

before
executing it.

gitlab-runner verify --delete

gitlab-runner
unregister

This command allows to unregister one of the registered runners. It expects to enter a full URL and the runner's token. First get the runner's details by executing

gitlab-runner
list

:

test-runner     Executor=shell Token=t0k3n URL=http://gitlab.example.com/ci/

Then use this information to unregister it, using the following command.

Warning: This operation cannot be undone, it will update the configuration file, so make sure to have a backup of

config.toml

before
executing it.

gitlab-runner unregister -u http://gitlab.example.com/ci/ -t t0k3n

Service-related
commands

The following commands allow you to manage the runner as a system or user service. Use them to install, uninstall, start and stop the runner service.

gitlab-runner
install
gitlab-runner
uninstall
gitlab-runner
start
gitlab-runner
stop
gitlab-runner
restart
gitlab-runner
status
Multiple
services
Access
Denied when running the service-related commands

All service related commands accept these arguments:

Parameter	Default	Description
--service-name	gitlab-runner	Specify custom service name
--config	See the configuration file	Specify a custom configuration file to use

gitlab-runner
install

This command installs GitLab Runner as a service. It accepts different sets of arguments depending on which system it's run on.

When run on Windows or as super-user, it accepts the

--user

flag
which allows you to drop privileges of builds run with the shell executor.

Parameter	Default	Description
--service-name	gitlab-runner	Specify a custom name for the Runner
--working-directory	the current directory	Specify the root directory where all data will be stored when builds will be run with the shellexecutor
--user	root	Specify the user which will be used to execute builds
--password	none	Specify the password for the user that will be used to execute the builds

gitlab-runner
uninstall

This command stops and uninstalls the GitLab Runner from being run as an service.

gitlab-runner
start

This command starts the GitLab Runner service.

gitlab-runner
stop

This command stops the GitLab Runner service.

gitlab-runner
restart

This command stops and then starts the GitLab Runner service.

gitlab-runner
status

This command prints the status of the GitLab Runner service.

Multiple
services

By specifying the

--service-name

flag,
it is possible to have multiple GitLab Runner services installed, with multiple separate configurations.

Run-related
commands

This command allows to fetch and process builds from GitLab.

gitlab-runner
run

This is main command that is executed when GitLab Runner is started as a service. It reads all defined Runners from

config.toml

and
tries to run all of them.

The command is executed and works until it receives
a signal.

It accepts the following parameters.

Parameter	Default	Description
--config	See #configuration-file	Specify a custom configuration file to be used
--working-directory	the current directory	Specify the root directory where all data will be stored when builds will be run with the shellexecutor
--user	the current user	Specify the user that will be used to execute builds
--syslog	false	Send all logs to SysLog (Unix) or EventLog (Windows)

gitlab-runner
run-single

This is a supplementary command that can be used to run only a single build from a single GitLab instance. It doesn't use any configuration file and requires to pass all options either as parameters or environment variables. The GitLab URL and Runner token
need to be specified too.

For example:

gitlab-runner run-single -u http://gitlab.example.com -t my-runner-token --executor docker --docker-image ruby:2.1

You can see all possible configuration options by using the

--help

flag:

gitlab-runner run-single --help

gitlab-runner exec

This command allows you to run builds locally, trying to replicate the CI environment as much as possible. It doesn't need to connect to GitLab, instead it reads the local

.gitlab-ci.yml

and
creates a new build environment in which all the build steps are executed.

This command is useful for fast checking and verifying

.gitlab-ci.yml

as
well as debugging broken builds since everything is run locally.

When executing

exec

you
need to specify the executor and the job name that is present in

.gitlab-ci.yml

.
The command should be executed from the root directory of your Git repository that contains

.gitlab-ci.yml

.

gitlab-runner
exec

will clone the current state of the local Git repository. Make sure you have committed any changes you want to test beforehand.

For example, the following command will execute the job named tests locally using a shell executor:

gitlab-runner exec shell tests

To see a list of available executors, run:

gitlab-runner exec

To see a list of all available options for the

shell

executor,
run:

gitlab-runner exec shell

If you want to use the

docker

executor
with the

exec

command,
use that in context of

docker-machine
shell

or

boot2docker
shell

. This is required to properly map your local directory to the directory inside the Docker container.

Limitations
of

gitlab-runner
exec

Some of the features may or may not work, like:

cache

or

artifacts

.

gitlab-runner
exec docker

can only be used when Docker is installed locally. This is needed because GitLab Runner is using host-bind volumes to access the Git sources.

Internal
commands

GitLab Runner is distributed as a single binary and contains a few internal commands that are used during builds.

gitlab-runner
artifacts-downloader

Download the artifacts archive from GitLab.

gitlab-runner
artifacts-uploader

Upload the artifacts archive to GitLab.

gitlab-runner
cache-archiver

Create a cache archive, store it locally or upload it to an external server.

gitlab-runner
cache-extractor

Restore the cache archive from a locally or externally stored file.

Troubleshooting

Below are some common pitfalls.

Access
Denied when running the service-related commands

Usually the service
related commands require administrator privileges:

On Unix (Linux, OSX, FreeBSD) systems, prefix

gitlab-runner

with

sudo

On Windows systems use the elevated command prompt. Run an

Administrator

command
prompt ([How to][prompt]). The simplest way is to write

Command
Prompt

in the Windows search field, right click and select

Run
as administrator

. You will be asked to confirm that you want to execute the elevated command prompt.

root@qa:~# sudo gitlab-ci-multi-runner register

Running in system-mode.

WARNING: The user-mode requires you to manually start builds processing:

WARNING: $ gitlab-runner run

Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/ci):
Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/ci): http://192.168.1.xx:8888/ci
Please enter the gitlab-ci token for this runner:

2KUKsjNLTe_asdffFrc6F

Please enter the gitlab-ci description for this runner:

[qa]: my-runner

Please enter the gitlab-ci tags for this runner (comma separated):

qatest

Registering runner... succeeded runner=2KUKsjNL

Please enter the executor: virtualbox, docker+machine, docker-ssh+machine, docker, docker-ssh, parallels, shell, ssh:

shell

Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!