## Summary The `release-platform` Terraform module (project: `gitlab-com/gl-infra/terraform-modules/release-platform`, registry: `gitlab.com/gitlab-com/release-platform/gitlab`) currently has no concept of a per-project bot identity that can act on **both** the canonical project and the security mirror. As a consequence, pipelines on the security mirror run as the auto-minted **project access token** of that project (a `project_<id>_bot_<hash>` user). PRATs are scoped to a single project, so this user cannot be a member of any other project. The deploy bridge job `📦 [<service>] Create deployment Helm chart` (emitted via `release-platform@v3.23` in `common-ci-tasks`, which includes `runwayctl@v4.29.0:ci-tasks/service-project/helm-chart.yml`) therefore fails with `failure_reason: downstream_bridge_project_not_found` whenever it runs on the security mirror — even though the runway deployment project exists. From the PRAT bot's point of view that project is invisible, so the bridge cannot start a downstream pipeline on it. Reproduced on `gitlab-org/security/release-platform-canary` pipeline [`2488025735`](https://gitlab.com/gitlab-org/security/release-platform-canary/-/pipelines/2488025735), bridge job [`14139607672`](https://gitlab.com/gitlab-org/security/release-platform-canary/-/jobs/14139607672). This issue extends the scope of the (already-closed) parent work item `gitlab-com/gl-infra/software-delivery&50` ("[WS1] infra-mgmt terraform module (3-mirror configuration)"): the 3-mirror module was completed there, and we now need to add a cross-project identity to make the security mirror's pipelines actually functional end-to-end. ## Proposed solution Each Release-Platform project gets a **GitLab group service account** (under `gitlab-com`) with a SAAT in Vault. The SA is added as a maintainer (configurable) of the canonical and security mirror projects, **and** is used as the mirror commit author so that pipelines on the security mirror run as the SA. The SA's username is exposed as a module output so that a follow-up MR on `gitlab-com/gl-infra/platform/runway/provisioner` can drop it into the `members:` list of the corresponding entry in `config/runtimes/<runtime>/workloads.yml` — which closes the loop and grants the SA maintainer on the deployment project, allowing the `trigger:` bridge to start the downstream pipeline. The SA is provisioned **unconditionally** (not opt-in), matching the always-on shape of the existing canonical/security/build/push-mirror modules. Opt-in would hide the same silent-pipeline-break this issue is fixing. Scope is intentionally constrained: - gitlab.com only (canonical + security mirror are both there). - No cross-instance plumbing, so no membership on the dev.gitlab.org build mirror, and no service-account declaration on `ops.gitlab.net`. ## Module surface change (`release-platform`) A single new variable, with sensible defaults so existing callers don't need to pass anything: ```hcl # variables.tf variable "service_account" { description = <<-EOF Configuration for the per-project GitLab group service account that acts as the cross-project bot identity for the canonical and security mirror projects. The SA is always created — it is required for the security mirror's pipelines to trigger downstream deployment pipelines on the runway deployment project. It lives under the `gitlab-com` root group on gitlab.com, is added as `access_level` on both canonical and security mirror projects, has a SAAT with `api` scope minted and stored in Vault, and is intentionally NOT added to the build mirror (dev.gitlab.org — different instance). All fields here have working defaults; pass `service_account = {}` or omit the variable entirely to get the standard behaviour. EOF type = object({ name_suffix = optional(string, "release-bot") # username = "<path>-<name_suffix>" access_level = optional(string, "maintainer") vault_secret_relative_path = optional(string, "service-account/token") token_rotation_days = optional(number, 30) }) default = {} validation { condition = contains( ["guest", "reporter", "developer", "maintainer", "owner"], var.service_account.access_level ) error_message = "service_account.access_level must be one of: guest, reporter, developer, maintainer, owner." } } ``` ### Resources (new file `service_account.tf`) ```hcl locals { sa_username = "${var.path}-${var.service_account.name_suffix}" } data "gitlab_group" "gitlab_com" { full_path = "gitlab-com" provider = gitlab.canonical } resource "gitlab_group_service_account" "bot" { group = data.gitlab_group.gitlab_com.group_id name = "Release Framework Bot — ${var.name}" username = local.sa_username provider = gitlab.canonical } resource "gitlab_group_service_account_access_token" "bot" { group = data.gitlab_group.gitlab_com.group_id user_id = gitlab_group_service_account.bot.service_account_id name = "release-framework-${var.path}-saat" scopes = ["api"] rotation_configuration = { expiration_days = var.service_account.token_rotation_days rotate_before_days = 7 } provider = gitlab.canonical } resource "vault_kv_secret_v2" "bot_token_canonical" { mount = "ci" name = "${module.canonical.vault_secrets_path}/${var.service_account.vault_secret_relative_path}" data_json = jsonencode({ token = gitlab_group_service_account_access_token.bot.token username = local.sa_username }) } resource "vault_kv_secret_v2" "bot_token_security" { mount = "ci" name = "${module.security.vault_secrets_path}/${var.service_account.vault_secret_relative_path}" data_json = jsonencode({ token = gitlab_group_service_account_access_token.bot.token username = local.sa_username }) } ``` ### `main.tf` changes — pass SA into project module + rewire push-mirror Membership is added via the downstream module's `members` input (non-authoritative `for_each` on `user_id`, verified safe). The canonical→security push-mirror is rewired to use the SAAT instead of auto-minting its own PRAT, by setting `custom_mirror_token` on the existing `push-mirror` submodule (the variable already exists upstream; no change to the downstream module needed). ```hcl module "canonical" { # ... existing fields ... members = { (gitlab_group_service_account.bot.service_account_id) = { access_level = var.service_account.access_level } } } module "security" { # ... existing fields ... members = { (gitlab_group_service_account.bot.service_account_id) = { access_level = var.service_account.access_level } } } module "mirror_canonical_to_security" { # ... existing fields ... # token = { name = "mirror-canonical-to-security" } # REMOVE custom_mirror_token = { username = local.sa_username user_id = gitlab_group_service_account.bot.service_account_id token = gitlab_group_service_account_access_token.bot.token } } ``` The build mirror is left alone: `mirror_security_to_build` continues to mint its own PRAT. This keeps the change scoped to gitlab.com → gitlab.com. Build pipelines are not the source of any failing bridge, so this trade-off is fine. ### Outputs ```hcl output "service_account_username" { description = "Username of the per-project service account bot. Drop this value into runway/provisioner workloads.yml `members:` to grant maintainer on the deployment project." value = local.sa_username } output "service_account_user_id" { description = "User ID of the per-project service account bot." value = gitlab_group_service_account.bot.service_account_id } output "service_account_vault_secret_paths" { description = "Vault KV-v2 secret paths where the SAAT is stored, on canonical and security." value = { canonical = "${module.canonical.vault_secrets_path}/${var.service_account.vault_secret_relative_path}" security = "${module.security.vault_secrets_path}/${var.service_account.vault_secret_relative_path}" } } ``` ### Provider requirements (`versions.tf`) Add `vault` to `required_providers` (alongside the existing `gitlab` aliases): ```hcl required_providers { gitlab = { ... } # unchanged vault = { source = "hashicorp/vault", version = ">= 4.0" } } ``` ## Files affected (in scope of this issue) In the `release-platform` module repo only: - `variables.tf` — add `variable "service_account"`. - `outputs.tf` — three new outputs (above). - `versions.tf` — add `vault` to `required_providers`. - `service_account.tf` — **new file**, SA + SAAT + Vault writes. - `main.tf` — pass SA via `members` to canonical and security; pass `custom_mirror_token` to `mirror_canonical_to_security`. - `README.md` — `terraform-docs .` regenerates the auto-generated section. Manually add a "Per-project service account" subsection under "Capabilities". - `tests/service_account.tftest.hcl` — **new file**, see Testing below. ## Follow-up MRs (described, **not** in scope of this issue) 1. **`infra-mgmt`** — bump `gitlab.com/gitlab-com/release-platform/gitlab` module version. No YAML change is required for the canary on the happy path; a `service_account:` block in `data/projects/release-platform/repos.yaml` is only needed if a project wants to override defaults. Surface `service_account_username` in the `release_platform_projects` output so consumers can find the value without inspecting state. 2. **`gitlab-com/gl-infra/platform/runway/provisioner`** — add the SA's username to `members:` in `config/runtimes/gke/workloads.yml` for the relevant entry. The provisioner's filter (`provisioner/modules/runtimes/gcp_gke/main.tf`) requires the user to be a member of the `gitlab-com` root group; group service accounts under `gitlab-com` satisfy that filter (verified empirically with `eng-infra-runway-provisioner`). ## Testing Native `terraform test`, run continuously during implementation rather than at the end. Tests in `tests/service_account.tftest.hcl`: 1. **Default — happy path.** With `service_account = {}` (or omitted entirely), plan creates: 1 SA, 1 SAAT, 2 Vault secrets, 2 `members` entries on canonical+security with access_level `"maintainer"`, and `mirror_canonical_to_security`'s `custom_mirror_token` populated (no auto-PRAT). 2. **Custom access level.** `service_account = { access_level = "developer" }` propagates `"developer"` to canonical+security memberships and nothing else changes. 3. **Invalid access\_level.** `access_level = "godmode"` should fail validation. 4. **Username derivation.** `service_account_username` output equals `<var.path>-release-bot` by default; overriding `name_suffix = "ci"` yields `<var.path>-ci`. 5. **No build-mirror disturbance.** `mirror_security_to_build` still uses the auto-PRAT path (`token = { name = ... }`); the SA is not propagated there. Other harness: | Layer | Tool | When | | ----------- | -------------------------------------------------------- | -------------------------- | | Format | `terraform fmt -recursive` + `pre-commit run --all-files` | per save | | Lint | `terraform validate`, tflint via pre-commit | per save | | Type/plan | `terraform init && terraform plan` against fixtures | after structural changes | | Tests | `terraform test` | every change | | Docs | `terraform-docs .` (updates README's TF\_DOCS section) | before commit | ## Considerations / trade-offs ### Why a `gitlab_group_service_account` under `gitlab-com` GitLab does not currently support project-scoped service accounts that can be members of other projects (PRATs are project-scoped but bound). A group service account under `gitlab-com` is the simplest scope that's visible to both `gitlab-org/<canonical>` and `gitlab-org/security/<mirror>`, and to the runway deployment project under `gitlab-com/gl-infra/platform/runway/deployments/`. Alternatives considered: - **Group SA under each project's canonical group** — doesn't work; canonical and security live in different subtrees. - **Reuse `eng-infra-runway-provisioner`** (already a guest of `gitlab-com` and `gitlab-org`) — overloads one identity across more pipelines than it was designed for; rejected in favour of one-bot-per-service. ### Why `members:` (usernames) in workloads.yml, not `groups:` The runway provisioner schema supports both. `members:` is the right grain because the SA is bound to a single service. Using `groups:` would require a parallel grouping nobody else maintains. ### Why `maintainer` as the default access level `semantic_release` needs to push tags and create GitLab releases. Branch protections in this module set `push_access_level = "no one"` and `tag_create_access_level = "maintainer"`. So the SA needs at least Maintainer on canonical/security to push tags. The bridge job needs Developer on the deployment project; that's controlled separately by the runway provisioner. ### Why two Vault writes (one per project) The module already writes secrets under each project's own `vault_secrets_path` via the downstream `vault-variables` submodule. Storing the SAAT under both is consistent and avoids cross-project Vault policies. Reversible later if a single-source-of-truth path is preferred. ## Open questions 1. **Vault secret writes — bespoke vs. submodule.** The downstream `gitlab-com/project/gitlab//modules/vault-variables` already writes secrets under a project's standard Vault path. We may want to reuse it instead of declaring our own `vault_kv_secret_v2` resources. Cleaner if it's straightforward; verify before implementation. 2. **SAAT rotation primitive.** The plan uses the provider's native `rotation_configuration`. The rest of GitLab.com infrastructure converged on a remote module sourced from `ops.gitlab.net` (`saat_*` pattern). For consistency we should consider invoking that module — trade-off is the cross-instance source for a self-contained module. 3. **Username collisions under `gitlab-com`.** The SA username `<path>-release-bot` is unique today but the `gitlab-com` group has many service accounts. Mitigation: prefix is implicit since `var.path` typically starts with the project key; consider a `precondition` validation at plan time. 4. **CI_JOB_TOKEN scope on the deployment project.** Out of scope here — the bridge fails on the per-user permission check, not the CI_JOB_TOKEN check. CI_JOB_TOKEN allowlist work is tracked separately under `runway-job-permissions`. ## Non-goals - Provisioning the SA on `dev.gitlab.org` for the build mirror, and rewiring `mirror_security_to_build` accordingly. Build pipelines are not the source of any failing bridge; follow-up if it ever becomes useful. - Any change under `infra-mgmt/environments/ops-gitlab-net/`. - Editing `runway/provisioner` `workloads.yml` (one-line follow-up MR — described above). - Rewriting the `release-platform` common-ci-tasks component or runwayctl `helm-chart.yml`. The bridge logic itself is fine; only the identity running it is broken. ## References - Failing pipeline: <https://gitlab.com/gitlab-org/security/release-platform-canary/-/pipelines/2488025735> - Failing bridge job: <https://gitlab.com/gitlab-org/security/release-platform-canary/-/jobs/14139607672> - MR that exposed the failure (bumped common-ci-tasks to v3.23): <https://gitlab.com/gitlab-org/software-delivery/release-platform-canary/-/merge_requests/51> - Component that emits the bridge: `templates/release-platform/template.yml@v3.23` in `gitlab-com/gl-infra/common-ci-tasks` - Bridge definition: `ci-tasks/service-project/helm-chart.yml@v4.29.0` in `gitlab-com/gl-infra/platform/runway/runwayctl` - Deployment project: <https://gitlab.com/gitlab-com/gl-infra/platform/runway/deployments/release-platform-canary> - Parent work item: gitlab-com/gl-infra/software-delivery&50