Make DeployToken#token routable
What does this MR do and why?
Mints deploy tokens in the routable token format, behind the new routable_deploy_token feature flag (gitlab_com_derisk, default off).
With the flag on, DeployToken#token carries a routing payload: c (the cell ID, added by default), o (the organization ID), and p (the project ID) or g (the group ID), depending on what the token belongs to. The HTTP Router uses this payload to route a deploy token minted on a cell other than the Legacy Cell back to that cell. This matters for requests where the token is the only thing the router can route on, such as docker login with a deploy token. The router side already exists (session_token_header_authorization_basic_routable_token), so no router change is needed.
- Flag actor: the top-level namespace of the token's project or group, so project and group tokens under the same top-level group are rolled out together.
- Compatibility: Rails still stores and compares the whole token and never decodes the payload. Existing tokens keep their format, and tokens minted while the flag is on keep working if it's turned off.
- Length: a routable deploy token is about 60–70 characters instead of 25. The encrypted value still fits
deploy_tokens.token_encrypted(varchar(255)), even with the largest IDs and a 20-character instance prefix. - Secret detection: adds a "GitLab Deploy Token (routable)" client-side pattern, so a routable deploy token is reported in full under its own name. Before this, it matched the deploy token pattern only on its first 20 characters, and in full only through the generic routable runner token pattern.
Rollout: the flag is off by default, so merging changes nothing. It will be enabled on the staging non-Legacy cell first, to confirm that a deploy token minted there is routed back to it, then on staging, GitLab.com and the production cells. Steps, monitoring and rollback are in the rollout issue: #635847.
This follows the same approach as the routable cluster agent tokens: encrypted: :required with routable_token: behind a gitlab_com_derisk flag.
References
- Closes #597463 (closed)
- Epic: &18122
- Cells container registry routing: gitlab-com/gl-infra/tenant-scale/cells-infrastructure/team#964 and gitlab-com/gl-infra/tenant-scale/cells-infrastructure/team#917
- Design: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/routable_tokens/ and https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/container_registry_routing_service/#routable-tokens
- HTTP Router rule for routable tokens in
Authorization: Basic: gitlab-org/cells/http-router!1410 (merged) - Precedent, routable cluster agent tokens: !204550 (merged)
- Rollout issue: #635847
Screenshots or screen recordings
There's no UI change. Only the token value shown once after creation changes:
| Before | After |
|---|---|
gldt- followed by 20 random characters |
gldt-<base64 payload>.01.<payload length><crc32> |
How to set up and validate locally
-
In the Rails console, create a deploy token with the flag off, then with it on:
project = Project.find_by_full_path('<group>/<project>') user = User.find_by(username: 'root') create = ->(name) { Projects::DeployTokens::CreateService.new(project, user, name: name, scopes: [:read_repository, :read_registry]).execute[:deploy_token] } Feature.disable(:routable_deploy_token) create.('flag-off').token # => "gldt-" followed by 20 characters Feature.enable(:routable_deploy_token, project.root_namespace) token = create.('flag-on').token -
Decode the routing payload:
length = token[-9, 2].to_i(36) decoded = Base64.urlsafe_decode64(token[-(13 + length), length]) decoded[-1 - decoded[-1].ord...-1] # => "c:1\no:<organization ID>\np:<project ID>", IDs in base36 -
Check that the token still authenticates:
git clone "http://<deploy token username>:<token>@127.0.0.1:3000/<group>/<project>.git" -
Paste the token into an issue comment. The secret detection warning lists it as
GitLab Deploy Token (routable). -
Optional, with the GDK HTTP Router enabled: run
gdk tail gitlab-http-router, then send:curl -i -u '<deploy token username>:<token>' 'http://127.0.0.1:3000/jwt/auth?service=container_registry&offline_token=true'The router log shows
ruleApplied: session_token_header_authorization_basic_routable_token.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.