Introduction

GitLab CI runners register with the GitLab instance using a registration token. Starting with GitLab 16.0, project and group-level registration tokens were deprecated in favor of authentication tokens. After a GitLab upgrade, old registration tokens stop working, preventing new runners from registering and causing CI/CD pipeline failures for projects that depend on specific runners.

Symptoms

  • Runner registration fails with 403 Forbidden or Registration token is invalid
  • New runners cannot be added to the project or group
  • Existing runners continue working but cannot be re-registered if they lose connection
  • Error message: ERROR: Registering runner... failed runner=abc123 status=403 Forbidden
  • Error message: Runner registered with GitLab but cannot pick up jobs

Common Causes

  • GitLab upgrade to 16.0+ deprecated project/group registration tokens
  • Registration token was manually revoked after the upgrade
  • Runner registration script still referencing the old token
  • Runbook or CI/CD documentation not updated with new authentication method
  • Automation (Terraform, Ansible) using the deprecated token endpoint

Step-by-Step Fix

Prevention

  • Plan runner token migration before upgrading GitLab to 16.0+
  • Update all automation (Terraform, Ansible, scripts) to use the new runner API
  • Document the new runner registration process in the CI/CD runbook
  • Monitor runner registration failure rates after any GitLab upgrade
  • Use the GitLab Terraform provider for runner management to avoid token issues
  • Set up alerts for runners that go offline and cannot re-register