gitlab runners – installation and basics


One of a number of posts on GitLab CI, see the gitlab-runner tag.

Initial goal is to add syntax checking, validation, etc., to my puppet control-repo.

It took me a little while to piece it together, and these are my notes.  The starting page for official docs is but there’s pockets in other places such as, plus the GitLab server has docs built in (

  • You need to upgrade runners alongside GitLab servers; there’s a limited window of compatibility. The repo and package names changed from v10.
  • The connection seems to be initiated from the runner, which means ports open on the GitLab server, nothing needed on the runner.
    • Log entries by the runner suggest it can be configured to listen as well.
  • Don’t install a runner on the GitLab server.

High level steps

  1. Set up repository and GPG keys for both packages and repo
  2. Install appropriate version of runner for the server
  3. Get registration token
  4. Run gitlab-runner register
  5. Configure runner as needed on server, eg: restricting projects or protected branches only.

Raspberry Pi

  • There are ARM packages for the GitLab runner, but for RHEL flavours not for armv7l – only arm and armhf.
  • There’s raspian packages for armhf and armel. Maybe there’s life in my ancient Pi!  (nb – the main docs don’t list raspian as supported)

RPM Repository

The repo page gives a bunch of options, including:

The puppet method uses the packagecloud module.  Two reasons for not using it

  • It creates a remarkable number of resources,
  • Open issues suggest that it’s not properly idempotent: it keeps trying to reinstall the GPG keys.

I kept it simple and puppetised the repo config plus the GPG keys, sort of ..

Two GPG keys are required;  that’s explicit in the supplied yum config.  (One looks like a key, one looks like a directory, but it’s a key as well.)

# rpm -q gpg-pubkey --qf '%{VERSION}-%{RELEASE} %{SUMMARY}\n'  | grep -i gitlab
880721d4-5b2bdf3b gpg(GitLab, Inc. <>)
e15e78f4-55310c0e gpg(GitLab B.V. (package repository signing key) <>)

Note that both the repository and the packages are signed; which I’d not seen before, and it also serves them over https.

I had problems with the second key:  I’ve installed it, and it still failed to cope with the signed repository.

  • Manually installing gitlab-runner prompts to import the key, and then it works.
  • Repositories are a yum thing, rpm signing is needed for both rpm and Yum.
  • I suspect that repository keys aren’t stashed as rpm keys, and so some investigation is needed.
  • I’ll update this page if I work out what’s going on.

Runner Configuration and Registration

On Centos 7/RHEL7, the gitlab-runner package (11.10.1) will

  • Create a gitlab-runner user and group; home directory /home/gitlab-runner
  • Create a systemd service and start it.

The service config provides some clues:

ExecStart=/usr/lib/gitlab-runner/gitlab-runner "run" "--working-directory" "/home/gitlab-runner" "--config" \
    "/etc/gitlab-runner/config.toml" "--service" "gitlab-runner" "--syslog" "--user" "gitlab-runner"

On the gitlab server runners admin page ( there are instructions:

Set up a shared Runner manually

    1. Install GitLab Runner
    2. Specify the following URL during the Runner setup: URL
    3. Use the following registration token during setup: TOKEN
    4. Start the Runner!

Step 1 links to

Don’t miss the ‘install via repositories’ link at the top –

If you stumbled into the manual instructions that are directly below (for Linux, MaCOS, Windows etc) then your package install already did all those bits.

The installation docs then link to registration docs ..

Admin vs. project or group

Docs indicate that runners can also be registered from specific projects or from repository groups.

  • This maybe desirable, as the registration token will have limited scope.
  • It would also be necessary .. if you don’t have admin rights.

Non-interactive registration

# gitlab-runner help
     exec                  execute a build locally
     list                  List all configured runners
     run                   run multi runner service
     register              register a new runner
     install               install service
     uninstall             uninstall service
     start                 start service
     stop                  stop service
     restart               restart service
     status                get status of a service
     run-single            start single runner
     unregister            unregister specific runner
     verify                verify all registered runners
     artifacts-downloader  download and extract build artifacts (internal)
     artifacts-uploader    create and upload build artifacts (internal)
     cache-archiver        create and upload cache artifacts (internal)
     cache-extractor       download and extract cache artifacts (internal)
     cache-init            changed permissions for cache paths (internal)
     health-check          check health for a specific address
     help, h               Shows a list of commands or help for one command
# gitlab-runner help register
  • there’s a huge number of parameters available, including banks of options for docker, parallels, virtualbox, k8s, AWS and GCP. (not libvirt or kvm, ho hum)
  • –token is not for registration
Token specified trying to verify runner...         
WARNING: If you want to register use the '-r' instead of '-t'. 
ERROR: Verifying runner... is removed
  • .. and you need to tell it how it’s going to do stuff
PANIC: Invalid executor specified                  
Unregistering runner from GitLab succeeded

In summary:

# gitlab-runner register --url --registration-token abcde --non-interactive --executor shell

Other executors

The documentation – – covers off how to do docker and others interactively;  just a case of finding the right parameters.

Final steps

Shared vs. project-restricted

  • Set up at the admin level, the runner is shared by default.
  • Enable it for one or more projects, then it becomes restricted. This is one-way.

Other settings

  • There’s an optional protected option for the runner, which is documented on the CI README linked above.
  • If selected, the runner won’t run against branches which aren’t set as protected in the repository.
  • This could help with some of the security issues, as typically there’s approval to get code merged into protected branches.

Security challenges

reset the registration token

  • Exposure of the registration token which could be used as a vector to access to variables and code.
  • Once the runner is registered, reset the registration token in the GUI. I’ve done limited testing of this; couldn’t see any issues.
  • Future runners need to use a different token. If this is impractical, best not to use an admin token – use one that’s more restricted.
  • There’s a button on the admin screen to reset it, other procedures need to be followed if a more project specific token was used.

shell executors aren’t secure

  • The same user runs any jobs that the runner picks up.


Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s