Introduction
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 https://docs.gitlab.com/runner/ but there’s pockets in other places such as https://docs.gitlab.com/ee/ci/runners/README.html, plus the GitLab server has docs built in (gitlab.example.com/help/ci/quick_start/README)
- 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
- Set up repository and GPG keys for both packages and repo
- Install appropriate version of runner for the server
- Get registration token
- Run gitlab-runner register
- 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:
- curl a script and execute it
- puppet
- manual instructions
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. <support@gitlab.com>)
e15e78f4-55310c0e gpg(GitLab B.V. (package repository signing key) <packages@gitlab.com>)
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 (gitlab.example.com/admin/runners) 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 https://docs.gitlab.com/runner/install/
Don’t miss the ‘install via repositories’ link at the top – https://docs.gitlab.com/runner/install/linux-repository.html
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
- The documentation – https://docs.gitlab.com/runner/register/index.html – covers off interactive registration.
- gitlab-runner has lots of different modes (see also: https://docs.gitlab.com/runner/commands/README.html)
# gitlab-runner help
[..]
COMMANDS:
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 http://gitlab.example.com/ --registration-token abcde --non-interactive --executor shell
Other executors
The documentation – https://docs.gitlab.com/runner/register/index.html – covers off how to do docker and others interactively; just a case of finding the right parameters.
Final steps
- The registration details are put into /etc/gitlab-runner/config.toml
- The runner will pop up on the admin page.
- If you then edit the runner, the options therein are documented on: https://docs.gitlab.com/ee/ci/runners/README.html
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.
