Skip to content

Run gitlab-ci jobs on your workstation

GitLab CI is awesome. Throw a .gitlab-ci.yml in your project and gitlab does the rest.

As soon as your .gitlab-ci.yml grows, you may want to check if everything is right with syntax, etc. You can lint your .gitlab-ci.yml prior pushing, but for me it always ended up in a flood of debugging .gitlab-ci.yml commits anyways.

gitlab-runner exec

Fortunately gitlab-runner has an exec mode which allows you to run and debug jobs on your workstation without registering the runner or commit pollution.

$ gitlab-runner exec --help

Runtime platform                                    arch=amd64 os=linux pid=829705 revision=HEAD version=13.8.0
NAME:
   gitlab-runner exec - execute a build locally

USAGE:
   gitlab-runner exec command [command options] [arguments...]

COMMANDS:
     docker-ssh  use docker-ssh executor
     parallels   use parallels executor
     shell       use shell executor
     ssh         use ssh executor
     virtualbox  use virtualbox executor
     custom      use custom executor
     docker      use docker executor

OPTIONS:
   --help, -h  show help

Install gitlab-runner, select an executer and you're ready to go.

Limitations

Unfortunately running gitlab-runner exec has some limitations. Some environment variables are missing and must be set by hand (CI_REGISTRY for example). include does work only partially.

Example

This shows a pipeline-snippet building a python package.

.gitlab-ci.yml 
---

image: ${CI_REGISTRY}/docker/python-build:3.3.0

stages:
  - test
  - build
  - release

test:pylint:
  stage: test
  script:
    - pylint --exit-zero -f colorized src/

# [...]

To test jobs in the test-stage locally, run gitlab-runner exec <executor> <job> <options>:

gitlab-runner exec docker test:pylint \
  --docker-volumes /var/run/docker.sock \
  --docker-volumes /tmp/gl-cache \
  --docker-cache-dir /tmp/gl-cache \
  --cache-dir /tmp/gl-cache \
  --env CI_REGISTRY=registry.gitlab.io

Conclusion

It is a bummer that you can not use features like artifacs or include, maybe this will be a thing in the future. Anyways...

Running gitlab-runner exec prior committing pipeline related stuff is very easy and reduces commit spam massively in my case. It safes time and keeps my workstation a bit cleaner as a sideeffect, since more and more tools resides within containers.

Last update: March 22, 2021