Skip to content

docs: document OIDC immutability constraint and exempt claude.yml from SHA pinning #159

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

Open
don-petry wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document OIDC immutability constraint and exempt claude.yml from SHA pinning #159

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
15 changes: 15 additions & 0 deletions standards/agent-standards.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,21 @@ Every repository MUST have:
| `CLAUDE.md` | Project-level instructions for Claude Code | error if missing |
| `AGENTS.md` | Development standards for AI agents | error if missing |

## Compliance Exemptions — Files Agents Must Not Modify

The following files are structurally immutable. Agents must not open PRs that
modify them. No compliance finding will ever require a change to these files;
if an existing agent-created PR touches them, close it without merging.

| File | Reason |
|------|--------|
| `.github/workflows/claude.yml` | Anthropic OIDC invariant — any diff from the default branch causes `401 Workflow validation failed`; Claude Code cannot run on that PR |
| `.github/workflows/agent-shield.yml` | Security boundary — agents are not permitted to weaken security scanning; changes require explicit human review |

These files must be adopted verbatim from `standards/workflows/` and updated
only by merging a standards PR from `petry-projects/.github`, which propagates
to all repos via the `@v1` tag bump.

Comment on lines +17 to +31
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 21, 2026

Choose a reason for hiding this comment

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

🧹 Nitpick | 🔵 Trivial

LGTM — exemption section is well-scoped.

Clear rationale per file, and the "adopt verbatim / updated only via standards PR" instruction lines up with the Tier 1 stub contract in ci-standards.md. The LanguageTool "GitHub" capitalization hints on lines 25/26/29 are false positives — these are literal path/repo identifiers.

Minor suggestion: consider adding a machine-readable signal (e.g., a known list consumed by scripts/compliance-audit.sh) so the exemption is enforced at PR-open time rather than relying on agents reading this doc. Otherwise an agent that skips the doc will still attempt a compliance PR against claude.yml.

🧰 Tools
🪛 LanguageTool

[uncategorized] ~25-~25: The official name of this software platform is spelled with a capital “H”.
Context: ... | File | Reason | |------|--------| | .github/workflows/claude.yml | Anthropic OIDC ...

(GITHUB)

[uncategorized] ~26-~26: The official name of this software platform is spelled with a capital “H”.
Context: ...; Claude Code cannot run on that PR | | .github/workflows/agent-shield.yml | Security ...

(GITHUB)

[uncategorized] ~29-~29: The official name of this software platform is spelled with a capital “H”.
Context: ...ted only by merging a standards PR from petry-projects/.github, which propagates to all repos via the...

(GITHUB)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@standards/agent-standards.md` around lines 17 - 31, Add a machine-readable
exemption list and wire it into the existing compliance check so agents can’t
open PRs that modify those immutable workflow files: create a small JSON or YAML
file (e.g., a single-key list containing ".github/workflows/claude.yml" and
".github/workflows/agent-shield.yml" and any future entries) and update
scripts/compliance-audit.sh to read that file and reject PRs touching any listed
paths; also add a one-line reference in agent-standards.md next to the exemption
table pointing to this machine-readable source (and mention that the canonical
source of truth is the standards/workflows/ adoption process) so humans and
automation reference the same list.

### CLAUDE.md Requirements

- MUST reference `AGENTS.md` for development standards
Expand Down
40 changes: 40 additions & 0 deletions standards/ci-standards.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,6 +235,22 @@
AI-assisted code review on PRs and issue automation via Claude Code Action.
A copy-paste ready template is available at [`standards/workflows/claude.yml`](workflows/claude.yml).

> **OIDC security constraint — `claude.yml` is immutable on PR branches.**
> Anthropic's token endpoint validates that `.github/workflows/claude.yml` on
> a PR branch is byte-for-byte identical to the same file on the default branch.
> Any diff — including SHA-pinning the `uses:` line, adding a trigger, or
> changing a comment — causes the OIDC token exchange to fail:
> ```

Check failure on line 243 in standards/ci-standards.md

View workflow job for this annotation

GitHub Actions / Lint

Fenced code blocks should have a language specified 

standards/ci-standards.md:243 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md040.md

Check failure on line 243 in standards/ci-standards.md

View workflow job for this annotation

GitHub Actions / Lint

Fenced code blocks should be surrounded by blank lines 

standards/ci-standards.md:243 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "> ```"] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md031.md
> App token exchange failed: 401 Unauthorized — Workflow validation failed.
> The workflow file must exist and have identical content to the version
> on the repository's default branch.
> ```

Check failure on line 247 in standards/ci-standards.md

View workflow job for this annotation

GitHub Actions / Lint

Fenced code blocks should be surrounded by blank lines 

standards/ci-standards.md:247 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "> ```"] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md031.md
> Claude Code will not run on that PR. Agents must not open PRs that modify
> `.github/workflows/claude.yml`. The caller stub template now includes a
> `paths-ignore` guard that prevents this workflow from triggering on PRs that
> only change this file. See also [Action Pinning Policy](#action-pinning-policy)
> for the reusable workflow ref exemption.

Check failure on line 253 in standards/ci-standards.md

View workflow job for this annotation

GitHub Actions / Lint

Blank line inside blockquote 

standards/ci-standards.md:253 MD028/no-blanks-blockquote Blank line inside blockquote https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md028.md
Comment on lines +238 to +253
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 21, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🔴 Critical

Fix markdownlint failures in the OIDC callout — CI is red.

The fenced block inside the blockquote violates MD031 (no surrounding blank lines inside the blockquote), MD040 (missing language), and MD028 (blank line at 253 between this blockquote and the next breaks them into two). Pipeline is failing on MD031.

🛠️ Proposed fix 
 > **OIDC security constraint — `claude.yml` is immutable on PR branches.**
 > Anthropic's token endpoint validates that `.github/workflows/claude.yml` on
 > a PR branch is byte-for-byte identical to the same file on the default branch.
 > Any diff — including SHA-pinning the `uses:` line, adding a trigger, or
 > changing a comment — causes the OIDC token exchange to fail:
-> ```
+>
+> ```text
 > App token exchange failed: 401 Unauthorized — Workflow validation failed.
 > The workflow file must exist and have identical content to the version
 > on the repository's default branch.
 > ```
+>
 > Claude Code will not run on that PR. Agents must not open PRs that modify
 > `.github/workflows/claude.yml`. The caller stub template now includes a
 > `paths-ignore` guard that prevents this workflow from triggering on PRs that
 > only change this file. See also [Action Pinning Policy](`#action-pinning-policy`)
 > for the reusable workflow ref exemption.
-
 > **All three jobs require a checkout step.** The `claude` job (PR reviews), the

If the blockquote separation at line 253 is intentional (two distinct callouts), keep the blank line but ensure markdownlint config accepts MD028 — the current default does not.

🧰 Tools
🪛 GitHub Actions: CI

[error] 243-243: markdownlint-cli2 reported MD031/blanks-around-fences: Fenced code blocks should be surrounded by blank lines [Context: "> ```"].

🪛 GitHub Check: Lint

[failure] 253-253: Blank line inside blockquote
standards/ci-standards.md:253 MD028/no-blanks-blockquote Blank line inside blockquote https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md028.md

[failure] 247-247: Fenced code blocks should be surrounded by blank lines
standards/ci-standards.md:247 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "> ```"] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md031.md

[failure] 243-243: Fenced code blocks should have a language specified
standards/ci-standards.md:243 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md040.md

[failure] 243-243: Fenced code blocks should be surrounded by blank lines
standards/ci-standards.md:243 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "> ```"] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md031.md

🪛 LanguageTool

[uncategorized] ~239-~239: The official name of this software platform is spelled with a capital “H”.
Context: ...thropic's token endpoint validates that .github/workflows/claude.yml on > a PR branch ...

(GITHUB)

[uncategorized] ~248-~248: The official name of this software platform is spelled with a capital “H”.
Context: ...R. Agents must not open PRs that modify > .github/workflows/claude.yml. The caller stub ...

(GITHUB)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@standards/ci-standards.md` around lines 238 - 253, The MD lint failures are
caused by the fenced code block inside the OIDC security constraint blockquote:
add a language to the fence (e.g., ```text```), ensure there is a blank line
inside the blockquote before and after the fenced block (prefix those blank
lines with > to satisfy MD031/MD040), and remove the extra blank line that
separates this blockquote from the next callout so it isn't split (or if the
split is intentional, keep the blank line but update markdownlint config to
allow MD028); update the “OIDC security constraint — `claude.yml` is immutable
on PR branches.” block accordingly.

> **All three jobs require a checkout step.** The `claude` job (PR reviews), the
> `claude-issue` job (issue automation), and the `claude-ci-fix` job (CI failure
> response) each need `actions/checkout` **before** the `claude-code-action` step.
Expand Down Expand Up @@ -737,6 +753,30 @@
> example to a repository, always look up the current SHA for each action and
> pin to it with a version comment.

### Exception: Internal Reusable Workflow References

Calls to `petry-projects/.github` reusable workflows use tag references
(`@v1`, `@main`) — **not SHA pins** — and are exempt from this policy.

```yaml
# CORRECT — tag ref for internal reusable workflow
uses: petry-projects/.github/.github/workflows/claude-code-reusable.yml@v1

# WRONG — do not SHA-pin internal reusable workflow refs
uses: petry-projects/.github/.github/workflows/claude-code-reusable.yml@ee22b427cbce9ecadcf2b436acb57c3adf0cb63d
```

**Why:** Pinning the `uses:` line in a Tier 1 caller stub creates a diff from
the default branch. Anthropic's OIDC token endpoint validates that
`.github/workflows/claude.yml` on a PR branch is identical to the default
branch — any diff causes `401 Workflow validation failed` and Claude Code
cannot run on that PR.

The `@v1` tag on `petry-projects/.github` is managed deliberately (bumped only
on backward-compatible releases) and is not subject to tag-force-push risk
because the org controls the tag. **Do not open compliance PRs to pin these
references.**

Comment on lines +756 to +779
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 21, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
rg -nP -C3 'check_action_pinning|unpinned-actions' scripts/compliance-audit.sh

Repository: petry-projects/.github

Length of output: 998

🏁 Script executed:

sed -n '186,250p' scripts/compliance-audit.sh

Repository: petry-projects/.github

Length of output: 2532

🏁 Script executed:

rg -n 'petry-projects.*\.github' scripts/compliance-audit.sh | head -20

Repository: petry-projects/.github

Length of output: 2479

🏁 Script executed:

rg -n '@v1|@main' scripts/compliance-audit.sh | grep -i 'filter\|exempt\|exclude'

Repository: petry-projects/.github

Length of output: 48

🏁 Script executed:

sed -n '756,779p' standards/ci-standards.md

Repository: petry-projects/.github

Length of output: 1137

Add whitelist for petry-projects/.github reusable workflow tag refs to check_action_pinning().

The check_action_pinning() function currently lacks a filter to exempt petry-projects/.github/** reusable workflows tagged with @v1 or @main. Without this whitelist, the audit will flag these exempted refs as unpinned and create compliance PRs attempting to pin them to SHA, defeating the purpose of the exemption documented in ci-standards.md (lines 756–779). Update the grep filter to exclude petry-projects/.github/**@(v1|main) patterns.

🧰 Tools
🪛 LanguageTool

[uncategorized] ~758-~758: The official name of this software platform is spelled with a capital “H”.
Context: ... Reusable Workflow References Calls to petry-projects/.github reusable workflows use tag references ...

(GITHUB)

[uncategorized] ~770-~770: The official name of this software platform is spelled with a capital “H”.
Context: ...ic's OIDC token endpoint validates that .github/workflows/claude.yml on a PR branch is...

(GITHUB)

[uncategorized] ~775-~775: The official name of this software platform is spelled with a capital “H”.
Context: ...annot run on that PR. The @v1 tag on petry-projects/.github is managed deliberately (bumped only o...

(GITHUB)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@standards/ci-standards.md` around lines 756 - 779, The check_action_pinning()
audit currently flags tag refs for internal reusable workflows; update its
grep/filter logic so it explicitly excludes petry-projects/.github
reusable-workflow tag refs (e.g. patterns matching
petry-projects/.github/**@(v1|main)); modify the filter used in
check_action_pinning() to add a negative match or whitelist for
petry-projects/.github/**@(v1|main) so those tag refs are skipped and not
reported or used to create compliance PRs.

---

## Permissions Policy
Expand Down
12 changes: 12 additions & 0 deletions standards/workflows/claude.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,16 @@
# or `secrets: inherit`. These are required for the reusable to work.
# • If you need different behaviour, open a PR against the reusable in the
# central repo. The change will propagate everywhere on next run.
#
# WHY THIS FILE IS IMMUTABLE (agents: read before opening any PR here):
# Anthropic's OIDC token endpoint validates that this file on a PR branch
# is byte-for-byte identical to the file on the default branch. Any diff —
# even a whitespace or comment change — causes the token exchange to fail:
# "401 Unauthorized — Workflow validation failed"
# Claude Code will not run on that PR. Do not open compliance PRs against
# this file. Do not SHA-pin the `uses:` line — internal reusable workflow
# refs are exempt from the Action Pinning Policy (ci-standards.md
# §Action Pinning Policy). The @v1 tag is the correct, stable reference.
# ─────────────────────────────────────────────────────────────────────────────
#
# Claude Code — thin caller that delegates to the org-level reusable workflow.
Expand All @@ -25,6 +35,8 @@ on:
pull_request:
branches: [main]
types: [opened, reopened, synchronize]
paths-ignore:
- '.github/workflows/claude.yml' # OIDC invariant — see header above
issue_comment:
types: [created]
pull_request_review_comment:
Expand Down
Loading