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:

1. Builds of the same stage are run in parallel.
2. Builds of next stage are run after success.

Let's consider the following example, which defines 3 stages:

stages:
  - build
  - test
  - deploy
           

1. First all jobs of 

   build

    are executed in parallel.
2. If all jobs of 

   build

    succeeds, the 

   test

    jobs are executed in parallel.
3. If all jobs of 

   test

    succeeds, the 

   deploy

    jobs are executed in parallel.
4. If all jobs of 

   deploy

    succeeds, the commit is marked as 

   success

   .
5. 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:

1. 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.
2. 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://[email protected]/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:

1. only

    defines the names of branches and tags for which the job will be built.

2. 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:
    - [email protected]/gitlab-ce
  except:
    - [email protected]/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:

1. on_success

    - execute build only when all builds from prior stages succeeded. This is the default.

2. on_failure

    - execute build only when at least one build from prior stages failed.

3. 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:

1. Execute 

   cleanup_build_job

    only when 

   build_job

    fails
2. 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:

1. /etc/gitlab-runner/config.toml

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

   root

   )

2. ~/.gitlab-runner/config.toml

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

3. ./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 <[email protected]>

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:

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:

Non-interactive registration

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

You can specify the arguments when invoking the registration command:

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:

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.

[email protected]:~# 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!