How do I register/reregister a Gitlab Runner using a pre-made config.toml?

Question

I recently wanted to move a Gitlab runner that I had set up for my self-hosted Gitlab instance from being a project runner (i.e. running jobs only for a project) to being a group runner (so it could also run jobs for other projects in the same group). I wanted to retain the /etc/gitlab-runner/config.toml settings that I had painstakingly hand-written.

Luckily I backed up config.toml, because sudo gitlab-runner unregister -t ... -u ... deleted the whole configuration from config.toml.

In order to get the same config registered under the group instead of the project, I had to:

1. Register the runner in a paused state with a dummy configuration, with the group's registration token:

sudo gitlab-runner register \
  --non-interactive \
  --url <URL HERE>
  --registration-token <TOKEN HERE> \
  --executor docker \
  --docker-image docker:dind \
  --paused

2. Go into the new config.toml that this created and copy the runner's individual runner token.

3. Overwrite config.toml with my desired configuration.

4. Edit the config.toml and plug in the new individual runner token.

5. Start the Gitlab runner service (sudo systemctl start gitlab-runner).

6. Unpause the runner in the Gitlab web UI.

Even after doing all this, the Gitlab instance still sees the runner under the name it registered with in the dummy config, rather than the name in the config.toml.

Trying the --config option to gitlab-runner register didn't work at all; I think that just tells it where to save the config. It still prompted me for new settings to use instead of reading from the config.toml I pointed it at.

The Gitlab documentation on runner registration is all written around one shot gitlab-runner register commands with loads of options on them that essentially specify the whole config on the command line. I really don't want to translate my config.toml manually into a command line that turns around and rebuilds it (minus any comments, of course).

I can't believe that this is really the right workflow to re-register a runner with a new project/group/Gitlab instance, or to create a copy of a runner from a saved config. What am I missing here? How can I create a new Gitlab runner from an existing config.toml file?

Answer 1

There isn't an easy way to do what you want, from what I can find in the GitLab documentation and some open issues that they have.

Here is an issue that describes something similar to what you want:

https://gitlab.com/gitlab-org/gitlab-runner/issues/3540

Here is what I think is GitLab's goal with how to register runners:

https://gitlab.com/gitlab-org/gitlab-ce/issues/40693

I believe that the only thing that you can't change from the .toml file is the name of the runner, and maybe not the tags either. Then name is only created when you register the runner. I read something somewhere that you can change the tags of a shared runner, but I can't find it now.

Here is a workaround to make the process of registering a bit more automatic:

https://gitlab.com/gitlab-org/gitlab-runner/issues/3553#note_108527430

He used this API:

curl --request POST "https://gitlab.com/api/v4/runners" --form "token=<registration-token>" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"

Then he got the following response back:

{"id":401513,"token":"<runner-token>"}

He could then inject the runner-token into his already pre-made .toml file.

For you, it would have been possible to use the registration token for your group, and then to write in the description/name of the runner and the tags. You could then have re-used your config.toml and only changed the runner-token, and it should have worked.