[FF] cells_claims_jira_connect_installations -- Cells claims for Jira installations

Summary

Roll out the feature currently behind the cells_claims_jira_connect_installations feature flag.

This is the model-specific claims flag from the claims feature flag hierarchy. It starts claim creation on write: every JiraConnectInstallation then claims its forge_installation_xid and its client_key through the Topology Service.

The verification worker for this model has its own flag, tracked in gitlab-org/gitlab#624936. Enable this flag first, and let it settle before that one.

Note

Process and guidance live in the docs — this issue is just the commands and a place to track the rollout. "Rolling out" means incrementally enabling the flag on GitLab.com to validate stability — it is not the same as releasing the feature, which happens when the flag is removed. Feature flag controls · Feature flag lifecycle

What could go wrong?

Claim creation adds a Topology Service call to the create, update and destroy paths of JiraConnectInstallation. If the Topology Service refuses a claim, the write fails, so a Jira site could fail to install or to link a namespace.

forge_installation_xid is a new and empty column, so no backfill runs and no deduplication is needed. client_key is present on every row and has no cross-organization duplicates in production (aggregate counts only).

The flag defaults to off, so nothing changes until it is enabled.

Known risk: client_key format contract

The two sides validate differently. Rails checks only presence and per-organization uniqueness of client_key, storing any non-blank value. The Topology Service is stricter: it accepts the claim type CLAIM_TYPE_JIRA_CLIENT_KEY only when the value matches ^[A-Za-z0-9:._-]{1,255}$ (see the claim validation rules).

Atlassian gives no format guarantee. Atlassian documents clientKey as an opaque value. The value can also change when a customer imports Jira data. This gap was raised in a review comment on gitlab-org/gitlab!248948.

Every value in production fits the rule today. A Database Lab thin clone (snapshot 2026-08-28) shows 109,255 installations (aggregate counts only). None have a null client_key; all 109,255 match the rule. Characters in use are digits, lowercase letters, colon, period and hyphen; lengths run 10 to 41. 107,133 rows are 36 characters (a UUID) and 1,521 are 41 characters (a jira: prefix plus a UUID).

The risk. If Atlassian issues a value outside the rule, the Topology Service refuses the claim, and the write fails. A Connect installation or update would fail at write time, instead of degrading gracefully.

What to watch. After the flag is on, watch for claim rejection errors on JiraConnectInstallation writes.

Mitigations, if it happens. First and preferred: widen the Topology Service rule for this claim type. The 255 character cap is a defensive limit we chose, not an Atlassian contract. Second: mirror the rule as a Rails format validation, so failures happen early with a clear message.

Why we accept this risk. The whole install base fits the rule today, and the flag starts off.

Rollout

Run all production /chatops in #production and cross-post the results to #g_import. Background: incremental rollout process, feature actors.

Non-production

/chatops gitlab run feature set cells_claims_jira_connect_installations 50 --actors --dev --pre --staging --staging-ref
/chatops gitlab run feature set cells_claims_jira_connect_installations true --dev --pre --staging --staging-ref

Production — percentage rollout (wait ≥15 min between steps, watch dashboards):

/chatops gitlab run feature set cells_claims_jira_connect_installations <percentage> --actors

Or target specific actors instead:

/chatops gitlab run feature set --project=gitlab-org/gitlab,gitlab-org/gitlab-foss cells_claims_jira_connect_installations true
/chatops gitlab run feature set --group=gitlab-org,gitlab-com cells_claims_jira_connect_installations true
/chatops gitlab run feature set --user=jotolo_gl cells_claims_jira_connect_installations true

Before global rollout

Confirm the relevant gotchas before going to 100% — see enabling a feature for GitLab.com:

Cleanup

Remove the flag once deemed stable — see cleaning up. Track it here, or open a follow-up Feature Flag Cleanup issue. Remove the flag and its YAML definition from the codebase, then:

/chatops gitlab run release check https://gitlab.com/gitlab-org/gitlab/-/merge_requests/248948 19.4
/chatops gitlab run feature delete cells_claims_jira_connect_installations --dev --pre --staging --staging-ref --production

Rollback

/chatops gitlab run feature set cells_claims_jira_connect_installations false                                         # production
/chatops gitlab run feature set cells_claims_jira_connect_installations false --dev --pre --staging --staging-ref     # non-production
/chatops gitlab run feature delete cells_claims_jira_connect_installations --dev --pre --staging --staging-ref --production  # remove entirely
由 Jorge Tomás 编辑于