ADR-069: Repository identity comes from context or configuration, not literals¶
Status¶
Accepted 2026-10-26.
Context¶
The repository moved from Brad-Edwards/shifter to Brad-Edwards/bigrae. The
name was a literal in workflows, the ADR guard, Terraform defaults, bootstrap
defaults, operator scripts, and tests. A rename or a fork broke these places,
and some of them failed instead of skipping.
The literals answer different questions:
- Self-identity. A workflow refers to the repository that runs it. The runtime context already holds this value.
- Upstream-only jobs. A job must run only in the upstream repository, for example the Sonar scan that uses upstream secrets.
- Trust anchors. A cloud trust policy or a deployed validator states which repository it trusts. The token or the artifact cannot supply this value.
- Operator tooling. A script acts on a repository for a person. A clone can have upstream remotes, so the target must be explicit.
- Upstream references. Documentation links, the documentation site, the citation, package metadata, historical issue links, and provenance records name the project.
Established projects guard upstream-only jobs with a literal repository or owner
(for example Node.js, CPython, Django, Homebrew, and rust-analyzer). In a fork
these jobs skip. The GitHub CLI verifies an attestation against a --repo,
--signer-repo, or --signer-workflow value. GitHub Actions OIDC offers
immutable owner and repository IDs that do not change on a rename. The gh
default repository (gh repo set-default) is the per-clone target for gh
commands.
Decision¶
- Self-identity uses the runtime context. A workflow or build that refers
to its own repository uses
github.repository,github.repository_owner,github.repository_id,github.server_url, or the matchingGITHUB_*environment values. This includes attestation verification of artifacts that the same repository built, image source labels, and registry namespaces derived from the owner. - Upstream-only jobs compare immutable IDs. A job that must run only in the
upstream repository compares
github.repository_idandgithub.repository_owner_id, never the name. The IDs equal the values in the one identity declaration,docs/adr/repository-identity.json. In a fork the job skips. - Trust anchors come from deployment configuration. Cloud trust (AWS IAM
OIDC and GCP Workload Identity Federation) and deployed validators get the
trusted repository from deployment configuration: Terraform variables,
values that bootstrap resolves and the operator confirms, or deployment
environment values. Trust binds the immutable IDs. Code and modules carry no
default repository identity, with one narrow exception: the GCP Workload
Identity trust module (
platform/terraform/gcp/modules/cicd-oidc-identityand itsgcp/global/cicd-oidcroot) keeps agithub_org/github_repodefault. A mandatory, un-skippable static check (CKV_GCP_125, enforced byscripts/check_tf_gcp_wif_trust) must resolve the repository name to validate the trust grammar, and checkov scans without deployment variables. The immutablegithub_repository_id/github_owner_idstill have no default and are the binding anchor, so a fork or rename cannot federate. Real deployments set the name through per-environment tfvars; the default is read only by the scanner.purpose_contextsalso has no default. A GCP deployment without GitHub federation (ADR-070) setspurpose_contextsto{}and both IDs to empty strings explicitly. The module accepts empty IDs only without federation, andscripts/check_tf_gcp_wif_trustrejects a default on these variables. The provenance trust anchor of a GCP deployment issettings.release_trustin its root config: the immutable repository and owner IDs that sign its releases. CI passes the IDs of the running repository instead. - Operator tooling uses the
ghdefault repository. A script resolves its target from the clone'sghdefault repository (set withgh repo set-default, read withgh repo set-default --view), from an explicit argument, or from aGH_REPOvalue. When none is set, the script stops with a clear message. A script never usesgh repo viewto find its target, because without a default it selects an upstream remote. - Upstream references may name the project. Documentation links, the documentation site URL, the citation, package metadata, historical issue and pull request links, and provenance records may name the upstream project.
- The ADR guard enforces the rules. The
repository-identity-literalscheck fails when an executable or configuration file contains the declared repository name, owner and repository pair, repository or owner ID, or registry owner namespace, outside the declaration and the rule 5 references. Tests use synthetic identities.
Consequences¶
- A fork runs the same workflows. Upstream-only jobs skip in the fork.
- A rename changes the declaration, the
.ground-control.yamlgithub_repovalue, and the deployment configuration. Code does not change. - Each deployment states its trusted repository in its own configuration.
- An operator runs
gh repo set-defaultonce in each clone that has more than one remote.