CLAUDE.md

Behavioral rules for .github/workflows/** and .github/actions/**. This repository is a distribution source — consumers pin workflows and composites by commit SHA.

Design background: GitHub Workflows Design. Contracts: Specification.

Pins

Composition

Invoke shared or sibling scripts with run: + bash/source. Contexts are not expanded in uses:.

Path resolution

${GITHUB_ACTION_PATH} (same as ${{ github.action_path }} in composite run: steps) points to the pinned action directory in the runner's _actions/ cache — not the caller's GITHUB_WORKSPACE.

MUST NOT use ${GITHUB_WORKSPACE}/.github/actions/... in paths meant to work when the action is consumed remotely.

Reusable workflows and secrets

Reusable workflow rules:

1. MUST declare stable callee secret names (AGENT_TOKEN, BOT_APP_*, GITHUB_TOKEN, …).
2. MUST require callers to pass an explicit secrets: map (enables name remapping).
3. MUST NOT use secrets: inherit.
4. MUST NOT pass tokens via with: on reusable workflows.
5. When a reusable job sets environment:, environment-scoped secrets override caller-passed secrets with the same name — callers relying on remapped repo secrets should leave environment empty unless the environment defines those names.

Loop callers pass configuration via with: on the reusable; avoid caller-level env: blocks for loop caller workflows.

Input defaults and discovery (reusable portability)

Reusable workflows (ci-*, cd-*) are distribution artifacts. Their inputs.*.default values and embedded step logic MUST stay portable — do not bake in this repository's layout, agent install trees, or gitignore habits.

When reviewing or authoring a reusable workflow, ask: “Would this default or branch surprise a consumer with a different repo layout?” If yes, move it to the caller.

File prefixes: ci-* / cd-* (reusable), on-* (event caller), example/ (consumer template). Map key ordering: ORD-01 in companion github-actions-workflow rules.

Failure diagnostics

When a loop step records failure metadata for run logs or action outputs:

1. MUST redact sensitive text before persistence (shared lib/loop/redact.sh — do not duplicate patterns).
2. MUST record via shared lib/loop/failure_record.sh (loop_failure_record).
3. MUST export to GITHUB_OUTPUT via shared lib/loop/export_failure_diag.sh — do not add per-action export duplicates.
4. MUST NOT write raw git push, gh, or CLI stderr to committed logs without redaction.

Anti-patterns

pr_push and PR-revise concurrency

Design background: PR Revise Workflow Design.

Verification

Paired Bats under test/bats/github-actions/ when behavior changes (TEST-00). pr_push landing changes MUST include test/bats/.github/actions/loop-finalize/lib/push_target.bats.

Security

• Reference secrets only via ${{ secrets.NAME }} or ${{ github.token }}; never echo tokens.
• Keep permissions least-privilege; document zizmor: ignore[...] only with justification.
• Do not place real tokens in workflow examples or comments.
• Mask or redact sensitive values in failure messages and logs before persistence.