gitlab-runner exec usability improvements (mostly by supporting artifacts)

Status update: 2024-11-03

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

Description

As became clear from #312 (closed), it can be very desirable to do some testing of CI jobs locally before pushing it to the server. Otherwise, debugging CI can result in numerous tiny commits. gitlab-runner exec is a nice tool to do some local testing, but since we (at our company) started integrating artifacts more into our pipeline, it has started to become increasingly less usable as a local testing tool.

The problem is that many jobs declare dependencies on previous jobs, and thus have dependencies on the artifacts of such previous jobs. To my knowledge, it is now completely impossible to test those jobs locally with gitlab-runner exec, because I'm not aware of any way to work around this limitation. I tried gitlab-runner exec docker "build job" --docker-volumes pwd/some/dir:/some/dir, but that only works for mounts that are outside of the repo in the job (so target dir is outside of /builds/project-1).

Version info:

$ gitlab-runner -v
Version:      1.11.1
Git revision: a67a225
Git branch:   1-11-stable
GO version:   go1.7.5
Built:        Fri, 03 Mar 2017 12:35:58 +0000
OS/Arch:      linux/amd64

Proposal

There are several options to improve usability here. Any or a combination of them would be useful in my opinion.

Some suggestions:

  • Allow a gitlab-runner exec call to locally run a full pipeline, including artifact passing (maybe rename gitlab-runner exec-job and gitlab-runner exec-pipeline)
  • Allow volume mounts that help you put the required artifact files yourselves in the right place. Currently, --docker-volumes won't allow mounting into the scope of the repo.
  • Supply artifact zips as arguments. If multiple dependencies, you can supply them as a list: gitlab-runner exec --artifacts /tmp/artifact1.zip,/tmp/artifact2.zip,/tmp/artifact3.zip docker "build job"
  • Hold a local cache of artifacts, and make it possible to reuse those when applicable (i.e. when commit hash matches). NOTE: gitlab-runner exec --clear-cache might be a useful (necessary?) addition in that case.
  • Allow a job to be run on a copy of the current local repo dir, including uncommitted changes and ignored/untracked files.
  • Same as above, but instead of a copy, use the repo as a mount in docker. I.e. allow the whole repo dir to be used as a mount (at own risk of user). This way, you even receive the outputs back...
  • If a job has artifacts, place the artifacts.zip afterwards in the folder where the command was run... (or somewhere else using an argument This would be a useful addition.
  • Allow setting (overriding) of Environment variables if desired/needed (because they lack or are wrong in the local gitlab-runner exec environment), e.g. gitlab-runner exec --env CI_JOB_ID=99 docker "build job". Currently gitlab-runner exec docker --help shows the --env option of the docker executor. It works kindoff, e.g. this gitlab-runner exec docker "build job" --env TEST_VAR=99 works. But it won't be able to override existing variables, such as CI_JOB_ID.

NOTE: I purposefully put the arguments like this gitlab-runner exec --artifacts /tmp/artifact1.zip docker "build job" and not like gitlab-runner exec docker "build job" --artifacts /tmp/artifact1.zip. Because to me, it makes more sense to scope them as exec arguments, rather than docker-executor arguments. However, I don't really mind where they end up: either way would be fine.

Links to related issues and merge requests / references

Edited by Darren Eastman