From 09f19c6c59816e72f06fca27ca0fc420a0f5ddfc Mon Sep 17 00:00:00 2001 From: Jens Hausherr Date: Fri, 6 Nov 2026 18:27:20 +0100 Subject: [PATCH] docs: add ADRs for subject format selection --- README.md | 3 ++ ...001-immutable-subject-format-by-default.md | 32 +++++++++++++++++++ ...epository-setting-overrides-format-flag.md | 32 +++++++++++++++++++ 3 files changed, 67 insertions(+) create mode 100644 docs/adr/0001-immutable-subject-format-by-default.md create mode 100644 docs/adr/0002-repository-setting-overrides-format-flag.md diff --git a/README.md b/README.md index 7be43b7..82b46de 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,9 @@ If the repository uses a custom `sub` template, a warning is printed: the patter default template and will not match. GitHub Enterprise Server has no immutable subjects; use `--mutable` there. +Rationale: [ADR 1](docs/adr/0001-immutable-subject-format-by-default.md), +[ADR 2](docs/adr/0002-repository-setting-overrides-format-flag.md). + ## Releases Pushing a `v*` tag builds binaries for all platforms via diff --git a/docs/adr/0001-immutable-subject-format-by-default.md b/docs/adr/0001-immutable-subject-format-by-default.md new file mode 100644 index 0000000..e6b1830 --- /dev/null +++ b/docs/adr/0001-immutable-subject-format-by-default.md @@ -0,0 +1,32 @@ +# 1. Immutable subject format by default + +Date: 2026-11-06 + +## Status + +Accepted + +## Context + +GitHub Actions OIDC tokens identify the repository in the `sub` claim. The legacy format +`repo:OWNER/REPO:…` uses names only. After a rename, transfer or deletion, someone else can +register the old name and obtain tokens that match existing trust policies. + +GitHub introduced [immutable subjects](https://github.blog/changelog/2026-04-23-immutable-subject-claims-for-github-actions-oidc-tokens) +of the form `repo:OWNER@OWNER_ID/REPO@REPO_ID:…`. Repositories created after 2026-07-15 use it +by default; older ones keep the legacy format until they opt in. GitHub Enterprise Server does +not support it. + +## Decision + +Emit the immutable format by default. The extension resolves owner and repository IDs via the +API. `--mutable` selects the legacy format. + +## Consequences + +- Generated trust policies survive renames and cannot be claimed by a re-registered name. +- Resolving IDs costs no extra request: the repository lookup is already needed for canonical + name casing. +- Older repositories that have not opted in would get non-matching patterns. [ADR 2](0002-repository-setting-overrides-format-flag.md) + mitigates this by reading the repository's actual setting. +- GitHub Enterprise Server users must pass `--mutable`. diff --git a/docs/adr/0002-repository-setting-overrides-format-flag.md b/docs/adr/0002-repository-setting-overrides-format-flag.md new file mode 100644 index 0000000..8064dfb --- /dev/null +++ b/docs/adr/0002-repository-setting-overrides-format-flag.md @@ -0,0 +1,32 @@ +# 2. Repository setting overrides the format flag + +Date: 2026-11-06 + +## Status + +Accepted + +## Context + +Whether a repository issues immutable or legacy subjects ([ADR 1](0001-immutable-subject-format-by-default.md)) +depends on its creation date and opt-in state, which users often do not know. A pattern in the +wrong format silently never matches. + +`GET /repos/{owner}/{repo}/actions/oidc/customization/sub` returns `use_immutable_subject`. +The field was observed in API responses but not documented at the time of writing. The request +can fail for lack of permissions, and the field is absent on GitHub Enterprise Server. + +## Decision + +If the field can be read, it decides the format, and a note goes to stderr when it differs from +what the flags asked for. Only when it cannot be read do the default and `--mutable` apply. + +## Consequences + +- Output matches the repository's actual format without the user having to know it. +- Users cannot force a format against the repository setting, e.g. to prepare a policy before + opting in. Revisit with an explicit override flag if that need appears. +- If GitHub removes or renames the field, behaviour degrades to the flag-based default rather + than failing. +- Inheritance of an organization-level setting is not verified; the repository endpoint is + assumed to report the effective value.