## 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](https://docs.gitlab.com/ee/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)) we deprecated (but did not remove) the documented [`gitlab-runner exec`](https://docs.gitlab.com/runner/commands/#gitlab-runner-exec-deprecated) 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`](https://docs.gitlab.com/runner/commands/#gitlab-runner-exec-deprecated) 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](https://gitlab.com/gitlab-org/gitlab/-/issues/384107), 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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110972). ## 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 - [Unable to exec any docker job locally from Windows 10 host (with Docker Toolbox)](https://gitlab.com/gitlab-org/gitlab-runner/issues/4686) - Unable to use `include` - [Some YAML anchor not parsed](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/26413)