Skip to content

docs(agents): tag protection + mutable-ref exception (#505) #509

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
don-petry merged 2 commits into from
Jun 9, 2026
Merged

docs(agents): tag protection + mutable-ref exception (#505) #509

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2742b00
docs(agents): document release channel tags + mutable-ref exception (…
Jun 9, 2026
8938544
Merge branch 'main' into feat/issue-505-tag-protection
don-petry Jun 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,3 +67,30 @@ This is the `.github-private` org infrastructure repo for `petry-projects`. It c
- **Promotion:** this is currently a repo-local standard. To make it org-wide,
lift it into [`petry-projects/.github`](https://github.com/petry-projects/.github/blob/main/AGENTS.md)
(the org AGENTS.md / `standards/`) and have repos defer to it.

### Release channel tags & the mutable-ref exception

The agents (`pr-review`, `dev-lead`) are versioned via tags — see
[`docs/release/versioning.md`](./docs/release/versioning.md). Two kinds of tag exist per agent:

Comment on lines +73 to +75
- **Immutable releases** `<agent>/vX.Y.Z` — never moved or deleted; the audit trail and rollback targets.
- **Moving channel tags** `<agent>/stable` (later `/next`, `/ring*`) — what callers pin to; advanced on
promotion by **moving** the tag.

**Scoped exception to the SHA-pin standard.** The org standard requires SHA-pinning actions to avoid
mutable-ref supply-chain risk. That rule targets **third-party** actions. The channel tags above are
intentionally **mutable** and are an accepted, documented exception because they reference
**first-party** reusable workflows in this repo that we own. The exception is bounded by:

- The `release-channel-tags` repository **ruleset** (target: tags `pr-review/**`, `dev-lead/**`)
restricts `update` and `deletion`, with bypass limited to **OrganizationAdmin** and the automation
**Integration** app. Net effect: the dev-lead/pr-review agents (running as `GITHUB_TOKEN`) **cannot**
move or delete release tags; only an admin or the promotion automation can.
- Immutable `vX.Y.Z` tags are the real rollback targets; `scripts/cut-release.sh` refuses to overwrite
an existing release tag.
Comment on lines +89 to +90
- Channel-tag moves happen only via the (forthcoming) health-gated promotion workflow (#501); the
ruleset bypass will be tightened to that workflow's identity when it lands.

Compliance audits must therefore **not** flag `@pr-review/stable` / `@dev-lead/stable` (or other channel
tags) on first-party callers as "unpinned actions" — they are the sanctioned version-selection mechanism
(see the initiative analysis §5.1: `docs/initiatives/agentic-release-strategy.md`).

@gemini-code-assist gemini-code-assist Bot Jun 9, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

To improve navigability, consider formatting the reference to agentic-release-strategy.md as a clickable relative markdown link, similar to how other document references are handled in this file.

Suggested change
(see the initiative analysis §5.1: `docs/initiatives/agentic-release-strategy.md`).
(see the initiative analysis §5.1: [docs/initiatives/agentic-release-strategy.md](./docs/initiatives/agentic-release-strategy.md)).

Comment on lines +94 to +96
Loading