Investigate tag-based pinning for sibling-calling actions (immutable releases)

[potiuk]

Context

PR #831 surfaced a scaling concern raised by @ppkarwasz: actions that call sibling sub-actions (e.g. carabiner-dev/actions/ampel/verify calling carabiner-dev/actions/install/*) currently force us to allowlist two SHAs per release — the current version plus the previous version that the sibling refs resolve to (per github/community discussion #26245). This scales as 2 × siblings × versions and is wasteful against the 1000-pattern org cap.

ppkarwasz's full argument: #831 (comment)

Proposal under evaluation

1. Ask upstream authors (starting with @puerco / carabiner-dev) to enable immutable releases so their version tags can no longer be moved post-publication.
2. Ask the same authors to pin sibling sub-action refs by tag instead of by previous-version SHA.
3. Teach our verifier (gateway/gateway.py and friends) to accept tag-pinning when the tag is provably immutable, ideally with a pattern like owner/repo/sub-action@vX.Y.Z rather than @<sha>.

Open questions to resolve before implementing (3)

• Path-segment wildcards. Does GitHub's org allowlist actually expand patterns like carabiner-dev/actions/*@v1.2.0? All current wildcards in approved_patterns.yml are version-side (@*). If path wildcards aren't supported, the saving shrinks to "one pattern per (sub-action, version)".
• Immutability re-verification. GitHub's per-release "immutable" flag can be disabled by the repo owner on future releases. Either:
  • Re-check immutability at every audit run (network cost, rate-limit cost, requires API endpoint), or
  • Snapshot the flag at approval time and accept silent erosion of the guarantee.
• Policy update. README currently says "Always pin actions to exact commit SHAs, never use tags or branch references." Tag-pinning under immutability is a controlled exception — needs to be documented as such, not as a blanket relaxation.
• Threat model delta. What's the additional blast radius if a repo turns off immutable releases after approval and an attacker then moves a tag we've trusted? Compare against current SHA-pinning baseline.

Non-goals

• Replacing the current SHA-pinning policy as the default. SHA-pinning remains the strictly safer primitive; this is about a documented escape hatch for the sibling-action case.

Suggested next step

Pre-work spike to answer the path-wildcard question (1–2 hour test against a sandbox repo's allowlist). The answer flips the cost-benefit on (3) substantially.

[potiuk]

Upstream ask filed: carabiner-dev/actions#57 — covers (1) enabling immutable releases and (2) switching sibling refs from previous-version SHA to tag. Verifier-side work (3) remains in this issue's scope.

[potiuk]

Initial investigation results — answering the open questions one at a time. tl;dr the path-wildcard question (the biggest cost driver for proposal #3) is already answered favorably; the immutability mechanics are workable; the policy/pattern-shape work is the real engineering scope.

1. Path-segment wildcards — ✅ supported, already in production

approved_patterns.yml already contains path-wildcard entries in active use:

- golangci/*@*
- quarto-dev/quarto-actions/*@*
- r-lib/actions/*@*
- rustsec/*@*

The in-repo verifier (gateway/check_repository_actions.py:146) uses Python fnmatch, which treats * as matching across / (deliberately, per the comment at allowlist-check/check_asf_allowlist.py:120-121). Since these patterns sync to the GitHub org allowlist and reportedly work in production, GitHub's allowlist syntax accepts them too.

Conclusion: carabiner-dev/actions/*@v1.2.0 is syntactically viable on both sides.

2. Tag-form patterns (@vX.Y.Z) — zero production usage today

Distribution of the 332 current entries:

Form	Count
@<sha40>	226
@*	104
@sha256:... (docker)	2
@vX.Y.Z	0

So while GitHub's documented allowlist syntax supports tag-form (@v2.*, @v2), we'd be introducing a new pattern shape into our pipeline. Affected surfaces:

• gateway/gateway.py:create_pattern() — pattern generator. Need to emit @<tag> instead of @<sha> when source actions.yml entry is marked immutable.
• actions.yml schema — needs an immutable: true flag (or a separate tag-pinned: block) per release entry.
• README/policy docs — need to document the controlled exception.
• Optional: check_action_tags workflow (snazy's Verify GH action tag/SHA combinations #356, related work) — should treat immutable tags as as-good-as-SHA.

3. immutable flag — queryable via REST, currently false everywhere

GET /repos/{owner}/{repo}/releases/tags/{tag} returns an immutable: bool field. Quick survey:

Repo	Tag	immutable
carabiner-dev/actions	v1.2.0	false
actions/checkout	v4.2.2	false
actions/setup-node	v4.1.0	false

Immutable releases is opt-in and not yet widely adopted in May 2026, even by actions/*. Filed upstream ask for carabiner-dev/actions: carabiner-dev/actions#57.

4. Re-verification semantics — gate at approval time, not audit time

Per GitHub's release-immutability semantics (need to re-confirm against current docs): a release that was immutable when published stays immutable; the repo-level setting only affects future releases. So:

• At approval time (when adding carabiner-dev/actions/*@v1.2.0 to actions.yml), our verifier should GET releases/tags/v1.2.0 and require .immutable == true. If false, reject tag-form and require SHA-form.
• At audit time (subsequent automated checks), we don't need to re-check — the approved release can't become mutable after the fact.
• For new releases by the same upstream, we re-check .immutable at each new approval. If the upstream disabled immutability for v1.3.0, we go back to SHA-pinning for that version only.

This bounds the API cost to one call per new approval — trivial.

5. Threat-model delta vs. SHA pinning

Under the gated approach in (4), tag-pinning to a verified-immutable release is essentially equivalent to SHA pinning for that release — the tag can't be moved post-publication. Differences:

• Trust delta: we trust GitHub's immutability enforcement instead of our own SHA snapshot. Both are reasonable; both fail if the upstream repo is compromised in ways that affect either the artifact storage or the SHA-to-tag mapping at HEAD.
• No "silent erosion": my original concern in this issue's open-questions section was that immutability could be reversed silently. Per the release-level semantics above, that doesn't apply to already-approved releases.
• Mixed-mode hygiene: the policy should be "SHA-pinning is the default; tag-pinning is an opt-in escape hatch documented per actions.yml entry as immutable: true." This keeps SHA-pinning as the safer baseline.

Proposed next-step scope (estimate)

1. actions.yml schema: add immutable: true per-release flag — small.
2. gateway.py: emit tag-form pattern when immutable: true; emit SHA-form otherwise — small.
3. New pre-commit/approval check: when immutable: true is set, call GitHub API to confirm .immutable == true on the actual release — small + needs token in CI.
4. README + AGENTS.md: document the controlled exception, link to this issue — small.
5. Migrate carabiner-dev/actions/* to tag-form after upstream (Enable immutable releases and pin sibling actions by tag carabiner-dev/actions#57) enables immutable releases — gated on upstream.

Steps 1–4 can land independently of upstream cooperation; they're plumbing. Step 5 is the payoff.

Will hold off on opening PRs until we get traction on carabiner-dev/actions#57 — no point shipping the verifier change if there's no first adopter.

[potiuk]

cc: @ppkarwasz - WDYT?

[ppkarwasz]

Looks good to me, thanks! 💯

I imagine you already implemented it?