Skip to content

Local pipeline execution (Won't do)

Status update: 2024-08-16

  • There are no plans at this time to try an implement a solution for this problem with the current GitLab CI and Runner architecture.

  • The introduction of CI Steps and Step Runner may in the future be a viable path to providing similar capabilities.

Problem(s) to solve

  • "it's really hard to believe that "I want to run the pipeline locally" isn't sufficient. Have you ever written a complex .gitlab-ci.yml? It only takes one or two iterations of push-wait-fail before you think, "I wish I could iterate on this locally instead.”

  • "The whole notion that I have to add commits to my actual repository in order to validate that automation workflows actually work is ludicrous, but it's either that or just use thoughts and prayers."

  • To test changes in a pipline you have to check in your changes to your gitlab-ci.yml file to your project repository.

  • Is there a simple way to host a local Gitlab instance so that remotes don't need to be polluted with lots of testing commits? Not being able to test dirty working trees locally is not the end of the world, but it would be great to still have some way to run CI locally, especially for containerized code.

Background - history

  • In 10.0 (#2710 (closed) (closed)) we deprecated (but did not remove) the documented gitlab-runner exec functionality of gitlab-runner, since it was incomplete and hard to maintain. It was later un-deprecated (and the limitations section was added at the document link), but at the moment there is no more complete replacement for it and the fundamental issues with it were not resolved.

  • In 15.7, we re-announced the deprecation of the gitlab-runner exec command from the runner core code base. Initially our plan was to simply remove gitlab-runner exec from the Runner core code base in 16.0. However based on feedback from the user and customer community in this issue and the feedback issue, we have decided to work on a new local pipeline execution solution.

What does the current plan mean for gitlab-runner exec?

  • gitlab-runner exec remains deprecated. The planned removal milestone is now 17.0 (~ May 2024).

  • We will not add new features to gitlab-runner exec or work on known bugs or gaps. Note - this decision is subject to change. However, any change in direction is solely based on the outcome of the architecture blueprint.

Current Functionality - gitlab-runner exec

  • The gitlab-runner exec command allows you to run jobs locally, trying to replicate the CI environment as much as possible.

  • It doesn't need to connect to a GitLab instance, instead it reads the local .gitlab-ci.yml and creates a new build environment in which all the build steps in a single job are executed. For example, the following command will execute the job named tests locally using a shell executor: gitlab-runner exec shell tests.

Compatibility table - features based on .gitlab-ci.yml*

GitLab CI feature Available with exec Comments
image yes extended configuration (name, entrypoint) are also supported
services yes extended configuration (name, alias, entrypoint, command) are also supported
stages no exec can only run one job, independently from others
before_script yes supports both global and job-level before_script
after_script partially global after_script is not supported, only job-level after_script; only commands are taken in consideration, when is hardcoded to always
variables yes Supports default (partially), global and job-level variables; default variables are pre-set as can be seen in https://gitlab.com/gitlab-org/gitlab-runner/blob/master/helpers/gitlab_ci_yaml_parser/parser.go#L147
artifacts no
cache partially Regarding the specific configuration it may or may not work as expected
cache:policy no
environment no
only no
except no
allow_failure no exec just exits with the result of job; it's callers responsibility to decide if failure is OK or not
tags no
when no
dependencies no
coverage no
retry no
hidden keys no If explicitly asked to run, exec will try to run such job
YAML features yes Anchors (&), aliases (*), map merging (<<) are part of YAML specification and are handled by the parser
pages partially Job's script will be 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
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
Variables no
triggers no
schedules no
job timeout no hardcoded to 1 hour
[ci skip] no

Known issues

Edited by Darren Eastman