Configuring runners

It may be useful to know the IP address of a runner so you can troubleshoot issues with that runner. GitLab stores and displays the IP address by viewing the source of the HTTP requests it makes to GitLab when polling for jobs. The IP address is always kept up to date so if the runner IP changes it automatically updates in GitLab.

The IP address for shared runners and specific runners can be found in different places.

Determine the IP address of a shared runner

To view the IP address of a shared runner you must have admin access to the GitLab instance. To determine this:

1. On the top bar, select Menu > Admin.
2. On the left sidebar, select Overview > Runners.
3. Find the runner in the table and view the IP Address column.

Determine the IP address of a specific runner

To can find the IP address of a runner for a specific project, you must have the Owner role for the project.

1. Go to the project’s Settings > CI/CD and expand the Runners section.
2. On the details page you should see a row for IP Address.

Use tags to control which jobs a runner can run

You must set up a runner to be able to run all the different types of jobs that it may encounter on the projects it’s shared over. This would be problematic for large amounts of projects, if it weren’t for tags.

GitLab CI/CD tags are not the same as Git tags. GitLab CI/CD tags are associated with runners. Git tags are associated with commits.

By tagging a runner for the types of jobs it can handle, you can make sure shared runners will only run the jobs they are equipped to run.

For instance, at GitLab we have runners tagged with rails if they contain the appropriate dependencies to run Rails test suites.

Set a runner to run untagged jobs

When you register a runner, its default behavior is to only pick tagged jobs. To change this, you must have the Owner role for the project.

To make a runner pick untagged jobs:

1. Go to the project’s Settings > CI/CD and expand the Runners section.
2. Find the runner you want to pick untagged jobs and make sure it’s enabled.
3. Click the pencil button.
4. Check the Run untagged jobs option.
5. Click the Save changes button for the changes to take effect.

Below are some example scenarios of different variations.

runner runs only tagged jobs

The following examples illustrate the potential impact of the runner being set to run only tagged jobs.

Example 1:

1. The runner is configured to run only tagged jobs and has the docker tag.
2. A job that has a hello tag is executed and stuck.

Example 2:

1. The runner is configured to run only tagged jobs and has the docker tag.
2. A job that has a docker tag is executed and run.

Example 3:

1. The runner is configured to run only tagged jobs and has the docker tag.
2. A job that has no tags defined is executed and stuck.

runner is allowed to run untagged jobs

The following examples illustrate the potential impact of the runner being set to run tagged and untagged jobs.

Example 1:

1. The runner is configured to run untagged jobs and has the docker tag.
2. A job that has no tags defined is executed and run.
3. A second job that has a docker tag defined is executed and run.

Example 2:

1. The runner is configured to run untagged jobs and has no tags defined.
2. A job that has no tags defined is executed and run.
3. A second job that has a docker tag defined is stuck.

Use tags to run jobs on different platforms

You can use tags to run different jobs on different platforms. For example, if you have an OS X runner with tag osx and a Windows runner with tag windows, you can run a job on each platform:

windows job:
  stage:
    - build
  tags:
    - windows
  script:
    - echo Hello, %USERNAME%!

osx job:
  stage:
    - build
  tags:
    - osx
  script:
    - echo "Hello, $USER!"

Use CI/CD variables in tags

You can use CI/CD variables with tags for dynamic runner selection:

variables:
  KUBERNETES_RUNNER: kubernetes

  job:
    tags:
      - docker
      - $KUBERNETES_RUNNER
    script:
      - echo "Hello runner selector feature"

Configure runner behavior with variables

You can use CI/CD variables to configure runner Git behavior globally or for individual jobs:

• GIT_STRATEGY
• GIT_SUBMODULE_STRATEGY
• GIT_CHECKOUT
• GIT_CLEAN_FLAGS
• GIT_FETCH_EXTRA_FLAGS
• GIT_SUBMODULE_UPDATE_FLAGS
• GIT_DEPTH (shallow cloning)
• GIT_CLONE_PATH (custom build directories)
• TRANSFER_METER_FREQUENCY (artifact/cache meter update frequency)
• ARTIFACT_COMPRESSION_LEVEL (artifact archiver compression level)
• CACHE_COMPRESSION_LEVEL (cache archiver compression level)
• CACHE_REQUEST_TIMEOUT (cache request timeout)

You can also use variables to configure how many times a runner attempts certain stages of job execution.

Git strategy

You can set the GIT_STRATEGY used to fetch the repository content, either globally or per-job in the variables section:

variables:
  GIT_STRATEGY: clone

There are three possible values: clone, fetch, and none. If left unspecified, jobs use the project’s pipeline setting.

clone is the slowest option. It clones the repository from scratch for every job, ensuring that the local working copy is always pristine. If an existing worktree is found, it is removed before cloning.

fetch is faster as it re-uses the local working copy (falling back to clone if it does not exist). git clean is used to undo any changes made by the last job, and git fetch is used to retrieve commits made after the last job ran.

However, fetch does require access to the previous worktree. This works well when using the shell or docker executor because these try to preserve worktrees and try to re-use them by default.

This has limitations when using the Docker Machine executor.

A Git strategy of none also re-uses the local working copy, but skips all Git operations normally done by GitLab. GitLab Runner pre-clone scripts are also skipped, if present. This strategy could mean you need to add fetch and checkout commands to your .gitlab-ci.yml script.

It can be used for jobs that operate exclusively on artifacts, like a deployment job. Git repository data may be present, but it’s likely out of date. You should only rely on files brought into the local working copy from cache or artifacts.

Git submodule strategy

Requires GitLab Runner v1.10+.

The GIT_SUBMODULE_STRATEGY variable is used to control if / how Git submodules are included when fetching the code before a build. You can set them globally or per-job in the variables section.

There are three possible values: none, normal, and recursive:

• none means that submodules are not included when fetching the project code. This is the default, which matches the pre-v1.10 behavior.

• normal means that only the top-level submodules are included. It’s equivalent to:

  git submodule sync
  git submodule update --init
  

• recursive means that all submodules (including submodules of submodules) are included. This feature needs Git v1.8.1 and later. When using a GitLab Runner with an executor not based on Docker, make sure the Git version meets that requirement. It’s equivalent to:

  git submodule sync --recursive
  git submodule update --init --recursive
  

For this feature to work correctly, the submodules must be configured (in .gitmodules) with either:

• the HTTP(S) URL of a publicly-accessible repository, or
• a relative path to another repository on the same GitLab server. See the Git submodules documentation.

You can provide additional flags to control advanced behavior using GIT_SUBMODULE_UPDATE_FLAGS.

Git checkout

The GIT_CHECKOUT variable can be used when the GIT_STRATEGY is set to either clone or fetch to specify whether a git checkout should be run. If not specified, it defaults to true. You can set them globally or per-job in the variables section.

If set to false, the runner:

• when doing fetch - updates the repository and leaves the working copy on the current revision,
• when doing clone - clones the repository and leaves the working copy on the default branch.

If GIT_CHECKOUT is set to true, both clone and fetch work the same way. The runner checks out the working copy of a revision related to the CI pipeline:

variables:
  GIT_STRATEGY: clone
  GIT_CHECKOUT: "false"
script:
  - git checkout -B master origin/master
  - git merge $CI_COMMIT_SHA

Git clean flags

The GIT_CLEAN_FLAGS variable is used to control the default behavior of git clean after checking out the sources. You can set it globally or per-job in the variables section.

GIT_CLEAN_FLAGS accepts all possible options of the command.

git clean is disabled if GIT_CHECKOUT: "false" is specified.

If GIT_CLEAN_FLAGS is:

• Not specified, git clean flags default to -ffdx.
• Given the value none, git clean is not executed.

For example:

variables:
  GIT_CLEAN_FLAGS: -ffdx -e cache/
script:
  - ls -al cache/

Git fetch extra flags

variables:
  GIT_FETCH_EXTRA_FLAGS: --prune
script:
  - ls -al cache/

git fetch origin $REFSPECS --depth 50  --prune

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_UPDATE_FLAGS: --remote --jobs 4
script:
  - ls -al .git/modules/

git submodule update --init --depth 50 --recursive --remote --jobs 4

variables:
  GIT_DEPTH: "3"

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name

test:
  script:
    - pwd

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/project-name

test:
  script:
    - pwd

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_PATH

test:
  script:
    - pwd

variables:
  GOPATH: $CI_BUILDS_DIR/go
  GIT_CLONE_PATH: $GOPATH/src/namespace/project

variables:
  GET_SOURCES_ATTEMPTS: 3

variables:
  # output upload and download progress every 2 seconds
  TRANSFER_METER_FREQUENCY: "2s"

  # Use fast compression for artifacts, resulting in larger archives
  ARTIFACT_COMPRESSION_LEVEL: "fast"

  # Use no compression for caches
  CACHE_COMPRESSION_LEVEL: "fastest"

  # Set maximum duration of cache upload and download
  CACHE_REQUEST_TIMEOUT: 5