Skip to content

Improve discoverability of runner creation and registration docs and add clarity

Problem to solve

Based on user feedback, the information about the new runner registration workflow isn't always clear and is sometimes difficult to locate:

Feedback 1

#387993 (comment 1519511103)

Re: 🙄 Let me give more concrete feedback.

Here is my stream of consciousness based on my browser history working through this.

I was adding a new runner and got a 403 because my token was expired, cool let me figure out where I got that token. Google "gitlab runner token" -> Gitlab Token Overview. Ahh there it is a runner token! Which is deprecated I guess, fine what's the new thing? Click on deprecated -- uhh not exactly helpful. Okay what about Token Architecture? More promising -- hey authentication token that sounds like what I want! Okay no, never mind that's actually not related at all. That's for after registration. How about Registration tokens? Wait that takes me to the same page at Authentication token. Are they the same now? Well that's a dead end. Hey look Runner creation through API that looks perfect! Let's go look at that -- that uses the old token. Uhh???? Random Googling --- Maybe Registering runners? as;lasdkjfl;aksdjf of course the programmatic docs are deprecated. Googling -- HEY A MIGRATION GUIDE!. Thank god. Okay I need to use /user/runners to actually do this. What is heck is instance_type, group_type? Uhh okay it means the runner type is literally group_type, that's not a placeholder for a type of group. Weird phrasing but fine. Oh come on why is this one a JSON API, the other one was a form? Screw this, it's late I don't want to have to rewrite this whole part of the code. I'm just gonna use the old token.

@pedropombeiro THANK YOU! I have no idea how I could have discovered that blog post organically but that's exactly what I would have wanted to find. I wish there was a part where it called the registration API directly because that's the only way to idempotently register a runner but otherwise 🔥

Feedback 2

From Slack discussion (internal link)

erran 1 day ago

I think if I stumbled across the Changes to the gitlab-runner register command syntax within the first 20 minutes or two of trying to debug an issue that ended up being due to packages installed on my runner and not the token type being incorrect.

Early on in my using search in our docs pages and Google I found these pages:

  • Create a project runner with a registration token (deprecated)
    • Step 6 links to the Registering runners page rather than the Register with a runner registration token (deprecated) section. doesn't call out the legacy-compatible registration process like the blueprint does in Using the authentication token in place of the registration token. I failed to find "Create a project runner" referenced so struggled to understand whether provisioning

Runner authentication tokens (taken from blueprint)

After you create a runner and its configuration, you receive a runner authentication token that you use to register the runner During a transition period, legacy tokens (“registration tokens”) continue to be shown on the GitLab Runners settings page and to be accepted by the gitlab-runner register command. The legacy workflow is nevertheless discouraged in the UI. Users are steered towards the new flow consisting of creating the runner in the UI and using the resulting authentication token with the gitlab-runner register command as they do today. This approach reduces disruption to users responsible for deploying runners.

Simplified flow for context:

  1. I noticed the DAST community fork was missing a dast-fips runner.
  2. The Dynamic Analysis group shared a script which:
    1. Installs the gitlab-runner package.
    2. Calls the gitlab-runner register command with --registration-token "${REGISTRATION_TOKEN}" included as arguments.
    3. Starts the runner.
  3. I asked Contributor Success folks to "create a project runner registration token" since I thought that is what I needed. Given the script requiring .
  4. Lee walked through the UI to setup a project runner through the GitLab UI meaning he received a runner authentication token.
  5. I ran the script passing in the token from Lee (glrt-REDACTED) as REGISTRATION_TOKEN.
    1. I got back a warning around several flags the script included being ignored with no link to documentation to understand the implications.

At this point many jobs were succeeding on the new runner but some did not which led me on a wild goose chase through docs around the registration process to understand where we went wrong. 😅

WARNING: You have specified an authentication token in the legacy parameter --registration-token. To ensure minimal disruption to your workflow, this has triggered the 'legacy-compatible registration process' which has resulted in the following command line parameters being ignored: --locked, --access-level, --run-untagged, --maximum-timeout, --paused, --tag-list, and --maintenance-note. These parameters and the legacy-compatible registration process will be removed in GitLab Runner 17.0.

erran 🗓 5 hours ago The gitlab-runner register command’s legacy compatibility warning when using --registration-token glrt- could be updated to include a link to our docs on the legacy compatible mode. I think we could improve the legacy mode docs by explaining the implications of the warning and that in legacy compatible mode while the gitlab-runner process registers successfully that a user that’s a Maintainer must verify these ignored options which previously were respected at registration time. (edited)

Further details

Proposal

Several updates need to be made to improve the docs and reduce confusion (WIP):

📖 Docs

💻 Code

  • Improve phrasing of instance_type, group_type, or project_type for the runner_type attribute. The values imply that it's a classification of the type of group or project or instance. instance_runner, group_runner, or project_runner might be more intuitive and aligned with the docs.
  • In the warning returned for the legacy-compatible registration process:

Who can address the issue

TW for grouprunner with input from engineering.

Other links/references

Next GitLab Runner Token UI Workstream (&7633 - closed)

Edited by Fiona Neill