Moving GitLab runners to authentication tokens: what changes and how contained the work is
If your team runs self-managed GitLab Runner fleets that still register runners with legacy registration tokens, from pipelines, scripts or the Helm chart, the move to glrt- authentication tokens is a contained change to how runners are created and authenticated. The effort is set mainly by how many runners you operate and how many places in your automation and charts register them. The GitLab instance, its repositories and its pipelines keep running as they are.
The work centers on runner registration. You change where each runner's credential comes from: a token created in the UI or through the API, stored as a secret, and read by the runner manager or the Helm chart. Plan an inventory first. List every runner, its executor, the tags and scope it uses, and every script, Terraform module, Ansible role, container image or chart value that calls the registration endpoint or sets a registration token. Each item becomes a line in the cutover plan, and each secret store entry needs an owner.
The exact deprecation and removal timing for registration tokens depends on the GitLab Runner version you run and on the GitLab release it pairs with. Confirm that timing in the GitLab Runner documentation for your versions before you set a date, and keep Runner major and minor versions aligned with GitLab as the Runner documentation advises. Because the change touches runner credentials, verify that existing jobs still pick up on the new runners before you disable the legacy workflow, and record who signed off on each runner group. Ask your DeployOpen contact to confirm the inventory and cutover steps against your environment before work starts.
What maps cleanly from registration tokens to glrt- authentication tokens
This table compares how each part of the runner setup behaved under legacy registration tokens and how it works with glrt- authentication tokens, with a migration note for each. Read the migration column first, since it tells you what must be re-created and what can stay as it is. Confirm each field against the current GitLab Runner documentation before you rely on parity, because registration behavior and parameter names have changed across releases.
| Setup area | Legacy registration token | Authentication token (glrt-) | Migration note |
|---|---|---|---|
| Runner creation | Registration token is copied from the scope page and passed to register | Runner is created first in the UI or through the API, and the glrt- token is issued for that runner | Plan a create step for every runner; confirm the current registration command and flags in the runner docs |
| Runner identity | Identity is assigned when the runner registers with the instance | Identity is tied to the runner record created in GitLab, so the token belongs to one runner | Existing runners generally need new tokens; confirm whether any identity carries over before assuming it does |
| Scope (instance, group and project) | Scope comes from which registration token was used | Scope is set when the runner is created in the chosen instance, group or project | Choose the scope again for each runner and confirm that existing scope assignments map one to one |
| Tags and run-untagged settings | Tags and run-untagged are set at registration time | Tags and run-untagged are set on the runner record in GitLab | Re-enter tags and the run-untagged choice on the new record; confirm where the current docs expect each setting |
| config.toml on each host | Token and settings are written to config.toml during registration | Token is written to config.toml, and some settings may be read from GitLab instead | Confirm which keys remain in config.toml and which move to the runner record; keep executor and cache settings untouched |
| Automation that calls the registration flow | Scripts pass a registration token to the register command | Scripts must create or fetch a runner and use its glrt- token | Update pipelines, provisioning code and autoscaling bootstrap; confirm the API endpoints and parameters in the current docs |
| Helm chart secret | Chart reads a registration token from a Kubernetes secret | Chart reads a runner authentication token from a secret that you create | Create a new secret with the glrt- value and update the chart values; confirm the key names the chart expects in its version |
Documented ways to create authentication-token runners and update automation
Each path below creates or replaces a runner that authenticates with a glrt- token instead of a legacy registration token. Work through them in order on a test instance first, because the runner list is the one place that confirms each change took effect.
Create the runner in the GitLab UI
The UI creates a runner at the scope you choose (instance, group or project) and shows the authentication token once. Use it for a small number of runners or a first trial. Confirm in the GitLab Runner docs for your version which runner tags, run-untagged and lock settings the creation form exposes, because those settings are now set on the runner record rather than at registration. Record the token in your secrets manager at creation time, since you cannot retrieve it again from the UI.
Create runners through the GitLab API
Automation that provisions many runners should create them through the API so the token is captured by the pipeline that needs it. Confirm the runner creation endpoint, its required scope and the response field that carries the authentication token in the API reference for your GitLab version. Give the automation account the narrowest role that can create runners at the target scope, and make sure the returned token is written directly to your secrets store rather than to job logs.
Register a host with the authentication token
On each host, the runner registration command accepts the authentication token in place of a registration token. Confirm the exact flag names and whether the command still accepts a legacy token in your installed version, since the two modes differ in which settings are passed at registration. Run the command on one runner first, then check that the runner appears online in the runner list with the expected tags and executor before rolling the change to the rest of the fleet.
Update the Helm chart secret
If the runner runs through the GitLab Runner Helm chart, the authentication token belongs in a Kubernetes secret that the chart reads, not in chart values committed to Git. Confirm the secret key name and the chart value that references it in the chart documentation for your chart version. Replace the secret, roll the runner deployment, and confirm the pod logs show a successful connection to the GitLab instance before you delete the old registration token.
Update CI and configuration automation
Pipelines, infrastructure code and configuration management that pass registration tokens need new inputs. Search your repositories and automation variables for the legacy token variable and for any template that calls the registration command. Replace the value with a masked, protected variable holding the authentication token, and confirm the job that runs registration no longer depends on the old token. Keep a short list of every consumer so none is missed at the cutover.
Check the runner list after each change
After every creation, registration, secret update or automation change, open the runner list and confirm the runner's status, tags, scope and last contact time. Run a test job that uses each runner's tags so the check covers real execution, not only connectivity. Keep this as a repeatable step in your change record, because a runner that disconnects silently will stop accepting jobs without an obvious error in CI.
Migrating runner registration: inventory, parallel run, cutover and disabling the legacy workflow
This sequence moves every runner, host, Helm release and automation job from legacy registration tokens to authentication tokens without an outage, with a rollback point at each cutover.
Inventory every registration token consumer
Before changing anything, list every place a registration token is used: runner hosts with a config.toml, Kubernetes and Helm releases that hold the token in a secret, provisioning scripts, infrastructure-as-code modules, and CI jobs that call the registration API. Record the owner, the GitLab scope (instance, group or project), the executor and the tags each runner serves. Confirm the GitLab version and the Runner version on every host, and align them as the GitLab Runner documentation advises, since mismatched versions complicate the later cutover. The step is done when the inventory names every consumer and an owner for each, and you can state which runners carry production workloads.
Create authentication-token runners beside the legacy ones
In the GitLab UI or through the API, create new runners that use authentication tokens, which carry the glrt- prefix. Give each pilot runner distinct tags, such as a short migration tag, so that jobs only reach it when a pipeline asks for that tag. Keep the legacy runners registered and running, so that the existing fleet remains the rollback path. Store each new token in your secrets manager, not in a repository or a shared document. The step is done when the new runners appear as online in the GitLab project, group or instance runner list and report the expected executor and tags.
Move one low-risk workload to the pilot runner
Choose a pipeline that is low risk, has no deployment permissions and runs often enough to show results quickly. Point only that project at the migration tag, either by editing the job tags in its CI configuration or by temporarily assigning the runner to that project. Set a rollback point: the pipeline can return to the legacy tags with a single commit, and the legacy runners remain registered. Watch job pickup times, queue depth, cache and artifact behavior, and job logs across several runs, including a run that exercises the cache if you use one. The step is done when repeated jobs succeed on the new runner with no unexplained failures, and the team agrees the results match the legacy behavior.
Cut over group by group and update automation
Move the remaining projects in batches, starting with the groups that carry the least business risk and ending with production deployment runners. For each batch, update the job tags, then update the automation that created or registered runners: provisioning scripts, infrastructure-as-code variables and any API calls that used the legacy token. For Kubernetes deployments, replace the token in the Helm chart secret that the GitLab Runner chart reads, then roll the release and confirm the new pods register. Define a rollback point before each batch: revert the tag change and leave the legacy runner online until the batch is verified. The step is done when each batch has run successfully and the Helm release and automation jobs show the new token.
Confirm no job depends on a legacy runner
Once every batch has moved, check that no pipeline still requests a legacy tag and that the legacy runners have received no jobs for a full working cycle that includes scheduled pipelines, deployments and any infrequent jobs such as nightly or release builds. Search repositories and shared CI templates for hard-coded legacy tags or runner references that were missed in the inventory. Ask each owner from the first step to sign off on their consumers. Keep the legacy runners stopped but registered during this check, so a missed dependency shows up as a stalled job rather than a silent fallback. The step is done when the owners sign off and no job has been picked up by a legacy runner during the observation window.
Retire legacy runners and disable the legacy workflow
Unregister the legacy runners in GitLab, stop their services, and remove their configuration files from the hosts or retire the pods. Then disable the legacy registration workflow in the GitLab settings that your version exposes, and confirm the setting with the GitLab documentation for your release, since the options and their location can differ between versions. Delete stored registration tokens from configuration files, Helm values, vault paths and automation variables, and rotate any token that may have been exposed. Record the final runner inventory and the date of the change in your change management system. The step is done when no legacy registration path works, the stored tokens are removed, and the inventory matches what is actually running.
Updating the Helm chart secret and automation without stopping job pickup
The goal of this step is to swap the runner token that the GitLab Runner Helm chart reads without a window where no runner accepts jobs. Runners registered with a legacy registration token keep working after you create a glrt- authentication token for a new runner, so the safe order is to create the new runner, store its token in the cluster, roll the deployment, confirm that pods are polling with the new identity, and only then retire the old one. Before you change anything, confirm the secret key name the chart expects for the authentication token, the rollout behavior of the Deployment when its secret changes, and any other values that must match, in the chart documentation for the chart version you run. Those details differ between chart versions, and a wrong key name means pods start with no usable token.
Plan the cutover around everything that holds the registration token today. That includes CI/CD variables in the runner management project, the configuration repository or Helm values files, secret stores such as Vault, OpenBao or a cloud secrets service, and any provisioning scripts or infrastructure code that render config.toml or create runners. Inventory each consumer and record who owns it. Update one consumer at a time and check that the runner it serves still picks up jobs before moving to the next. Keep the old token valid until the last consumer has moved, because a forgotten script or pipeline variable will fail silently the moment the legacy token is disabled.
Run the rollout so that old and new pods overlap. Use a rolling update strategy with enough replicas that at least one healthy runner stays online during the change, and watch the job queue and runner status in the GitLab UI while pods restart. Pipelines that are already running will finish on the runner that picked them up. Treat the old token as a rollback path until jobs have run cleanly on the new runners for a period you agree with your platform team, then disable the legacy workflow and remove the old secret. Keep a dated record of which token each runner uses so that a later audit or incident review can tie a job to a specific identity.
What drives the effort of a runner token switch
This table lists the factors that change how much work the switch from registration tokens to glrt- authentication tokens will take. Read each row as a question to answer during inventory, then use the quote column to make sure the partner or internal team prices the same thing. The main takeaway is that the number of places registration is embedded matters more than the number of runners alone.
| Driver | What raises effort | What lowers effort | What to ask for in a quote |
|---|---|---|---|
| Runners and hosts | Many runner managers across VMs, clusters and sites, each with its own config.toml and no central record of runner names or tags | A single inventory of runners by host, with tags, scope and owner recorded before any change | An itemized inventory of every runner manager, runner and host in scope |
| Executors in use | Mixed shell, Docker, autoscaling and Kubernetes executors, each registered and restarted differently | One executor family per fleet, or a clear list of which executors need a new token and which only need a config update | Separate line items per executor family and the restart or redeploy steps for each |
| Pipelines and scripts that embed registration | Registration commands with legacy tokens hard-coded in provisioning scripts, Ansible roles, cloud-init or CI jobs | Registration centralized in one provisioning path, with tokens read from a secrets store at run time | Search and rewrite of every script, playbook and pipeline that calls registration, with a list of files changed |
| Helm releases and secret stores | Several Helm releases for the Runner chart, each with its own secret, values file or external secret reference | One release per cluster with the authentication token already held in a managed secret | Work to update each release, secret and rotation step, including how the secret is refreshed in each cluster |
| Teams that own runners | Runners shared across many teams with no named owner, so each cutover needs agreement from several groups | Ownership recorded per runner or group, with a named contact for each cutover window | Coordination time for each owning team, and who signs off the cutover for each group |
| Change control and approvals | Production change windows, CAB reviews or evidence requirements for each runner change | Standard change templates already approved for runner configuration updates | Whether change records, approvals and rollback plans are included, and how they are filed |
| Test coverage of deployment pipelines | Deployment jobs with no test runs, so a broken registration is found only at release time | Pilot runners and pipelines that exercise deploy, build and cache jobs before cutover | A pilot plan that names the pipelines tested and the pass criteria for each |
| Platform of the runner fleet | Runners on VMs with mixed operating systems, or OpenShift clusters with security context constraints to review | Runners on one platform with one deployment method and a single restart procedure | Platform-specific steps for VMs, Kubernetes or OpenShift, listed separately in the quote |
What goes wrong when runners are re-registered in the wrong order
Runner re-registration fails in predictable ways when the old and new runners overlap badly or when the tags, hosts and versions around them drift. The cards below cover the failures we see most often, with a prevention step and the check to run against the GitLab Runner documentation before each cutover.
Jobs stuck in pending
If the last runner carrying a matching tag is removed before its replacement registers and picks up work, jobs queue with no runner to run them. The pending queue is the first visible symptom, and it often appears only when a scheduled pipeline or a deployment job is next in line. Prevention: register the new runner, confirm it appears online and accepts a test job with the same tags, then remove the old one. Check the runner status and tag list in the project or group CI/CD settings before deleting anything.
Legacy token still active
Registration tokens remain usable until the legacy workflow is disabled, so a token copied into a script, CI variable, Ansible role or secrets store can still register new runners after the migration. The legacy token is a standing credential, and it is easy to miss because nothing fails when it is left in place. Prevention: inventory every location that holds a registration token, replace each with a runner authentication token, and only then disable the legacy workflow. Confirm the disable setting and the token rotation steps in the GitLab Runner documentation for your version.
Autoscaled hosts keep old configuration
Autoscaling groups build instances from a launch template, image or VM template that embeds a config.toml or registration step. When the group replaces a host, it can register again with a retired credential or an outdated runner definition, and the fleet looks healthy while it is wrong. Prevention: move the authentication token into the image or template source of truth, rebuild the template, and scale the group down and back up to confirm new hosts register. Check the Docker Autoscaler and fleeting plugin settings in the Runner documentation for how tokens reach each instance.
Runner and GitLab version drift
GitLab documentation advises keeping Runner major and minor versions aligned with the GitLab instance. Re-registering runners during a version change can mix a new GitLab server with older Runner binaries, which may behave differently in job handling or token support. Prevention: pin the Runner version, upgrade GitLab and Runner in an order your change record defines, and verify the version pairing on every runner after each step. Compare the version matrix and release notes in the Runner documentation before scheduling the cutover.
Tags changed mid-migration
Runner tags decide which jobs a runner picks up. If the replacement runner is registered with different tag names, or tags are edited on the old runner during the overlap, deployment and test jobs can route to a runner with the wrong trust level or to no runner at all. Tags must match exactly across the old and new runners before either is paused. Prevention: export the current tag list from every runner, register the new runners with identical tags, and run one job per tag. Confirm how tags are set at authentication time in the Runner documentation, since some settings are fixed once the runner is created.
No rollback after early deletion
Deleting the old runner as soon as the new one is created removes the only known-good path back if a config mistake or template error appears. Without the old runner, a rollback means creating and tagging a new runner under time pressure. Prevention: keep the old runner paused, not deleted, until the new runners have run the full set of production pipelines, and record the old runner IDs and token locations in the change record. Confirm in the Runner documentation how a paused or disabled runner behaves before relying on it for rollback.
Questions teams ask before switching runner authentication
How much effort does switching runner authentication take?
The effort depends mostly on how many runners you have, how many places register or reference them, and how many teams depend on those runners. A small fleet with one pipeline template and one Helm release is a short change. A large estate has more work in the inventory, in each automation script that calls the registration endpoints, and in each place a runner token is stored. Each runner needs a new authentication token created in the GitLab UI or API, and each stored token must be replaced and tested. Ask any partner to base the quote on a written inventory of runners, registration scripts, infrastructure as code modules, and Helm values, not on a headcount estimate.
What sets the timeline for moving runners to authentication tokens?
The timeline is set less by the token change itself than by the windows you can use and the number of approvals in between. Runner fleets that autoscale, run deployment jobs, or serve regulated teams usually need change windows, rollback plans and sign-off from the teams that own those pipelines. Confirm with your change board how long a change request takes, which days are frozen, and whether runner changes count as production changes. Also confirm your GitLab version and the Runner version, because the docs advise keeping them aligned, and an upgrade in the same window adds its own steps.
What does your team need to provide before the work starts?
Four inputs make the work predictable:
- A complete inventory of runners, including scope (instance, group or project), executor, host or cluster, and the teams that use each one.
- Administrator access to the GitLab instance to create runners and review tags, plus read access to the hosts or Kubernetes namespaces where runner managers run.
- Agreed change windows and a named owner for each affected pipeline, so cutover can be paused if a deployment is in progress.
- Write access to your secret store, such as the one that holds registration values for automation, so new tokens can be stored and old ones removed safely.
Missing any of these usually adds time at the start, not during the cutover.
Can an internal platform team switch runner authentication without a partner?
Yes, a platform team with GitLab administration skills and access to the runner hosts can usually do the change alone, provided it has time to work through the inventory and test each path. The parts that tend to take longer are finding every script, pipeline or Helm release that still uses a registration token, and confirming that nothing silently depends on the old workflow. A partner can help with the inventory, the test plan and the rollback steps, and can take on the build when internal capacity is limited. Either way, the scope and acceptance checks should be written down before the work begins.
Do we have to run legacy and new runner registration side by side?
A parallel run is not always required, but it is the safer choice when runners serve production deployments or many teams. You can create the new authentication token runners next to the legacy ones, move pipelines to them by tag or group in stages, and keep the legacy path available until the last automation has been switched. This avoids a single large cutover. For a small, self-contained fleet, a direct replacement within one change window can be acceptable if you have a tested rollback. Decide this based on how many pipelines depend on each runner and how quickly you can revert a configuration.
What happens to running jobs during the cutover?
Jobs already running on a runner generally finish on that runner, but jobs queued for it can wait, fail or move depending on tags and how the runner is stopped. Plan the cutover around a quiet period and confirm how your runner manager handles shutdown, including autoscaled instances that may be terminated. Pipelines that deploy to production should not start during the window. Test the behavior on a non-production runner first, and confirm the exact shutdown and job handling in the GitLab Runner documentation for your version, which is linked from the GitLab Runner documentation reference on this page.
How do we confirm the legacy registration workflow is safe to disable?
Confirm it with evidence, not with a date. Before disabling the legacy workflow, check that every runner registered in your inventory now uses an authentication token, that every automation and Helm chart secret has been updated, and that a test pipeline runs on each runner pool. Review logs for registration attempts that still use the old path over a full working cycle, and make sure no scheduled jobs, infrastructure modules or disaster recovery scripts reference it. Record the results in the change ticket. If a check fails, keep the legacy path enabled and fix the source of the failure before trying again.
Which parts of the change carry the most security risk?
The main risks are exposure of the new token and loss of control over old tokens. Authentication tokens act as credentials for the runner, so they should live only in your secret store, never in pipeline variables visible to projects or in version control. Rotate or remove old registration values once the cutover is confirmed, and limit who can read the secret store entries. Runners that serve deployments should be restricted to protected branches or specific groups. Check your access reviews afterward so that no former automation account keeps the ability to register runners.
How DeployOpen scopes, delivers and supports runner authentication changes
DeployOpen plans and carries out the move from legacy runner registration tokens to authentication tokens inside your own GitLab and runner infrastructure. Work is agreed as a fixed-scope engagement, with each step documented so your team can run the fleet afterward.
How we scope
- Inventory every runner registration path, including scripts, infrastructure code and Helm values that still depend on legacy tokens.
- Define in writing which runner managers, groups and projects move to authentication tokens, and which stay untouched during the change.
- Agree the cutover window, rollback steps and the evidence your change process requires before any work starts.
How we build
- Create new runners in the GitLab UI or through the API, and record which tags and protected settings each runner keeps.
- Update automation, the config.toml files and the Helm chart secret so that every runner manager authenticates with a glrt- token.
- Test job pickup and registration on a non-production runner first, then confirm each production fleet before the legacy workflow is disabled.
How we hand over
- Deliver a runbook that lists each runner, its owner, its token location and the rotation steps your team should follow.
- Document the disabled legacy workflow, the verification checks performed and any exceptions your team agreed to keep.
- Walk your platform and security engineers through the changed registration flow so they can repeat it for new runners.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer if you want DeployOpen to watch the runner fleet over time.
- Track runner version alignment with your GitLab version, so that changes to token handling are planned alongside GitLab upgrades.
- Confirm with your GitLab release notes and your own environment any dependency on token behavior before each upgrade or runner change.
