On *nix systems when GitLab Runner is
executed as super-user (
root
):
/etc/gitlab-runner/config.toml
On *nix systems when GitLab Runner is
executed as non-root:
~/.gitlab-runner/config.toml
On other systems:
./config.toml
Most of the commands accept an argument to specify a custom configuration file,
so you can 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.
Do not use killall or pkill for graceful shutdowns if you are using shell
or docker executors. This can cause improper handling of the signals due to subprocessess
being killed as well. Use it only on the main process handling the jobs.
If your operating system is configured to automatically restart the service if it fails (which is the default on some platforms) it may automatically restart the runner if it’s shut down by the signals above.
The registered runner is
added to the
configuration file
.
You can use multiple configurations in a single installation of 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.
non-interactive.
Runners can be registered directly by using the GitLab
Runners API
but
configuration is not generated automatically.
It expects the runner’s name (or URL and ID), and an optional PAT if
resetting by runner ID. The PAT and runner ID are intended to be used if the
token has already expired.
With the --all-runners option, it resets all the attached runners’ tokens.
This feature was deprecated in GitLab 15.7
and is planned for removal in 17.0. Pipeline syntax and validation simulation are available in the GitLab pipeline editor. This change is a breaking change.
Not all features of
.gitlab-ci.yml
are supported by
exec
. Please
check what exactly is supported in the
limitations of
gitlab-runner exec
section.
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
clones 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 executes 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.
Other options are also available:
To view all possible configuration options, use
--help
:
gitlab-runner exec--help
To specify the path of the CI/CD configuration file, if your project doesn’t use the default
.gitlab-ci.yml
, use
--cicd-config-file
.
To set the job execution timeout (in seconds), use
--timeout
.
The default of
1800
means that the execution times out after 30 minutes.
Regarding the specific configuration it may or may not work as expected.
YAML features
yes
Anchors (
&
), aliases (
*
), map merging (
<<
) are part of YAML specification and are handled by the parser.
pages
partially
Job’s script is executed if explicitly asked, but it doesn’t affect pages state, which is managed by GitLab.
Compatibility table - features based on variables
GitLab CI feature
Available with
exec
Comments
GIT_STRATEGY
yes
GIT_CHECKOUT
yes
GIT_SUBMODULE_STRATEGY
yes
GIT_SUBMODULE_PATHS
yes
GIT_SUBMODULE_UPDATE_FLAGS
yes
GIT_SUBMODULE_DEPTH
yes
GIT_SUBMODULE_FORCE_HTTPS
yes
GET_SOURCES_ATTEMPTS
yes
ARTIFACT_DOWNLOAD_ATTEMPTS
no
Artifacts are not supported.
RESTORE_CACHE_ATTEMPTS
yes
GIT_DEPTH
yes
Compatibility table - other features
GitLab CI feature
Available with
exec
Comments
Secret Variables
no
triggers
no
schedules
no
job timeout
no
Hardcoded to 1 hour.
[ci skip]
no
Other requirements and limitations
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.
On Unix (Linux, macOS, FreeBSD) systems, prefix
gitlab-runner
with
sudo
On Windows systems use the elevated command prompt.
Run an
Administrator
command prompt.
The simplest way is to write
Command Prompt
in the Windows search field,
right click and select
Run as administrator
. You are asked to confirm
that you want to execute the elevated command prompt.
View pricing
to see all GitLab tiers and features, or to upgrade. Try GitLab for free
with access to all features for 30 days.
Get Help
If you didn't find what you were looking for,
search the docs.
If you want help with something specific and could use community support,
post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab
subscription).
