This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
See README.md for what each workflow does and how to call one from a consuming repo, and DESIGN.md for conventions and how release/renovate/testing fit together.
.github/workflows/*.yaml— the reusable workflows themselves (on: workflow_call), one per file, e.g.lint-yaml.yaml,build-docker-image.yaml,release-please.yaml. These are the product of this repo; everything else supports or exercises them..github/workflows/self-*.yaml— this repo consuming its own reusable workflows, either as tests against fixtures intest/, or as this repo's actual lint/release/renovate CI. See DESIGN.md for which is which.test/<name>/— fixtures for the matchingself-test-<name>.yaml(e.g.test/docker/Dockerfile,test/terraform/*.tf,test/chainsaw/*.yaml)..github/renovate.json+.github/renovate/*.json— this repo's own Renovate config (also a template for consumers).package.json,bun.lock— dependencies forlint-commit-messages.yaml, checked out by consumers that do not have their own package manifest.release-please-config.json,.release-please-manifest.json— config forrelease-please.yaml, used both by consumers and by this repo's ownself-release-please.yaml.zizmor.yaml— accepted-risk findings for thelint-zizmor.yamlgate (see comment in the file).
No build step. pre-commit (yamllint, markdownlint-cli2, commitlint) is the primary local tooling:
pre-commit install
pre-commit run --all-files
pre-commit run yamllint --all-files
pre-commit run markdownlint-cli2 --all-filesshellcheck is not a pre-commit hook; it runs only in CI, from two independent places:
# standalone scripts, as lint-shellcheck.yaml runs them (honours .shellcheckrc)
shellcheck --rcfile .shellcheckrc <file>...
# workflow `run:` blocks, as lint-github-actions.yaml runs them
jactionlint --profile correctness --shellcheck=shellcheckjactionlint passes --norc to shellcheck unless shellcheck.rcfile is set in
.github/jactionlint.yaml (this repo sets none), so .shellcheckrc does not apply to run:
blocks — suppress those findings with an inline # shellcheck disable=SCxxxx comment at the occurrence, never with a repo-wide disable.
Lint a commit message locally:
echo "fix(github-actions): re-pin actions/checkout to its current major" | npx commitlintbun install is only needed if changing package.json; it is not
required to edit or lint workflow YAML.
There is no way to run a workflow_call workflow locally — to exercise one's actual runtime behavior,
push a branch/PR that touches it (or its test/<name>/ fixtures), which triggers the matching
self-test-<name>.yaml in GitHub Actions. These also run weekly and via workflow_dispatch, so a
passing run days ago doesn't guarantee the workflow still works against current upstream tool versions.
The full taxonomy lives in .claude/rules/commits.md — read it before writing a commit message or a PR title. In short: type answers what kind of change, scope answers which maintenance surface, and the split between them turns on one question — does the thing you changed reach a consumer, or only this repo's own CI? commitlint enforces both the scope list and the rule that a type claiming shipped behaviour cannot sit on a scope that never ships.
This matters more than it looks: release-please derives the version bump and the changelog from the header, and squash-merge means the PR title is the released commit on a multi-commit branch.
- Every reusable workflow takes
git_ref(orsource_git_ref) as an explicit input rather than assuminggithub.ref— this is what letsself-test-*.yamlcall a workflow against a PR branch instead ofmain. When adding a new workflow, follow this pattern rather than readinggithub.refdirectly inside the called workflow. - When changing a reusable workflow's inputs, outputs, or secrets, update its matching table row in
README.md in the same change — README is the interface contract consumers read before
wiring a
with:/secrets:block, not just a summary. - An input's default is part of that interface too. Change one only for consumers' sake, never to suit
this repo — override it at the call site instead, as
self-test-aqua.yamldoes forupdate-aqua-checksums.yaml'ssemantic_commit_scope. Changing a default is a breaking change and belongs with a coordinated rollout. - An input's default is part of that interface too. Change one only for consumers' sake, never to suit
this repo — override it at the call site instead, as
self-test-aqua.yamldoes forupdate-aqua-checksums.yaml'ssemantic_commit_scope. Changing a default is a breaking change and belongs with a coordinated rollout. - If a workflow's runtime behavior changed (not just its
with:/secrets:surface), check whether a matchingself-test-<name>.yaml+test/<name>/fixture exists and update it rather than relying on manual verification — see DESIGN.md for the dogfooding pattern this repo uses. - Any tool version embedded in a workflow's
env:(not a lockfile) needs a# renovate: datasource=... depName=...comment above it so Renovate's custom regex manager can track it — copy the pattern from an existing workflow (e.g.HADOLINT_VERSIONinlint-hadolint.yaml) rather than inventing a new comment format. - Pin any new third-party Action reference to a commit SHA with the version as a trailing comment
(
uses: owner/repo@<sha> # vX.Y.Z). - Commit messages must pass commitlint (header ≤120 chars) — see
.claude/rules/commits.md for which type/scope to pick.
CHANGELOG.mdand version numbers are fully automated by release-please (this repo's own release mechanism, see DESIGN.md) — don't hand-edit either.