feat(action): install a verified release in one CI step

[jordonpeterson]

The documented use of this tool is a CI gate — sync --dry-run exiting 4, lint in a pipeline, audit across a fleet — and nothing said how the binary reaches the runner. The two routes that existed both misfit: go install installs a Go toolchain to compile a dependency-free binary that was already built six ways at release time, and a hand-rolled curl | sh step verifies build provenance only on a runner where gh happens to be signed in.

- uses: jordonpeterson/codeowners-tool@v0
- run: codeowners-tool lint --dry-run --github-repo ${{ github.repository }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The download stays in one place

setup.sh downloads nothing. install.sh already fetches, checksums and attests the archive, is already shellcheck'd, and is already gated by tools/supplychain; a second download here would be a second supply-chain surface for the same bytes. setup.sh resolves which release to ask for and hands off, then refuses to export a binary that is not the build the job asked for.

Provenance is verified by default rather than warned about: hosted runners ship gh, and the action hands it a token, so this is the one place the check can always run. provenance: require makes it fatal even where gh is missing.

A pin is a pin

The action ships from this repository, so @v0.0.29 reads as a version pin. Resolving it to the newest release would make it a pin in name only — the version someone writes down during an incident, naming a build they never ran. A full-version ref installs exactly that release; @v0 takes the newest; an explicit version: latest floats regardless of the ref.

That has a consequence for releases, so release.yml now:

• moves the v0 tag the recommended pin resolves through, after the release publishes — without it every consumer on @v0 freezes at the commit it first pointed at;
• cuts a release when action.yml or tools/action/setup.sh changes, since an action fix that cut no release would never reach that tag. Those two files and no glob over the package: its tests ship nothing, and releasing for them would advance the pin onto a commit whose action is byte-identical.

v0 does not exist yet. It is created by the first release after this merges, so uses: ...@v0 starts working then. The CI job below avoids the dependency by using uses: ./.

Testing

Both seams, because they fail differently.

Where	What it proves
tools/action/*_test.go (24 tests)	Drives the real setup.sh against a stub install.sh: version resolution (explicit, action-ref-derived, gh-resolved, install.sh-resolved, and explicit latest), provenance passthrough, the PATH/outputs export, and every refusal — malformed version, unknown provenance mode, Windows runner, failed install, a build that names no release, a build that is not the one requested, and any input spanning lines.
ci.yml job action	Runs the action the way a consumer's workflow does, against real releases, on ubuntu-latest and macos-latest, with provenance: require, then asserts a pinned v0.0.9 installs exactly that build.

Every load-bearing assertion was mutation-tested: removing the check it guards turns it red again. That covers the installed-vs-requested check, the action-ref default, the PATH-after-verify ordering, the release-tag check on the installed build, the latest-beats-the-ref branch, and both line-spanning guards.

Static gates live alongside them: the manifest must pass every INPUT_* the script reads (a composite action passes nothing implicitly, and a missing mapping is silent), the step must not ask for a shell it never uses, any uses: in action.yml must be SHA-pinned since it executes in the consumer's job with the consumer's token, and release.yml must move the major tag and trigger on the action's shipped files without globbing its tests.

Locally green: go test -race ./..., shellcheck, actionlint, and make docs with no diff.

Review

Eight findings, all real, all fixed — six from Copilot, two from following its threads into code it hadn't flagged. Four were the same underlying mistake, worth naming for the reviewer: validation that was one layer shallower than it looked.

• shell: bash for a step whose only command is sh — fails on minimal images that carry /bin/sh and no bash.
• The installed-build check only ran when a version was pinned, so the unpinned path would export a binary reporting dev and announce it as the installed version.
• version: latest fell through to the same branch as an unset input, so a workflow pinned at @v0.0.9 asking for latest silently got v0.0.9.
• install-dir reached the line-delimited $GITHUB_PATH, so a newline forged a PATH entry ahead of every later step.
• is_tag's anchored grep matches per line, so v0.0.9\nevil satisfied ^v[0-9]+\.[0-9]+\.[0-9]+$ and carried the rest through. The anchors were never doing the work.
• The refusals quoted the value they rejected, and the runner reads ::workflow commands:: from the start of a line — so rejecting a crafted input was itself the injection.
• The release trigger globbed tools/action/**, releasing for test-only changes.
• docs/INSTALL.md said "One step" above a two-step example.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HA6pqDeLuGi6szcbQdkr16

[Copilot]

🟡 Changes recommended

The new action should avoid unnecessary runtime dependencies (bash) and should validate the installed binary’s reported version format before exporting it to later steps.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a composite GitHub Action to install a checksum/provenance-verified codeowners-tool release in a single CI step, and updates CI/release automation plus docs to support and validate that distribution path.

Changes:

• Add action.yml + tools/action/setup.sh and a focused Go test suite to validate version resolution, provenance passthrough, PATH/outputs export, and refusal cases.
• Update CI to ShellCheck the new script and add an end-to-end workflow job that runs the action against real releases on Ubuntu/macOS.
• Update release workflow to cut releases when the action changes and to move the major v0 tag after publishing; update docs/README/CHANGELOG to document the CI install route.

File summaries

File	Description
tools/action/version_test.go	Tests version resolution semantics (pinned tag vs @v0 vs explicit input) and refusal cases.
tools/action/setup.sh	Action implementation: resolves release tag, delegates to install.sh, validates installed build, exports PATH/outputs.
tools/action/setup_test.go	Harness to execute setup.sh against a stub installer and stub gh.
tools/action/manifest_test.go	Gates manifest input/env mapping, SHA pinning of third-party actions, release workflow invariants, and doc discoverability.
README.md	Adds a one-line pointer to the recommended CI usage (uses: ...@v0).
docs/LINTING.md	Updates linting CI snippet to include the action install step.
docs/INSTALL.md	Adds a “GitHub Actions” install section and documents inputs/outputs.
CHANGELOG.md	Documents the new composite action and the major-tag movement behavior.
action.yml	New composite action manifest wiring inputs/outputs and token for gh.
.github/workflows/release.yml	Triggers releases on action changes and force-moves the major tag after publishing.
.github/workflows/ci.yml	Adds ShellCheck coverage for setup.sh and an e2e job exercising the action on Ubuntu/macOS.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

setup.sh currently treats an explicit version: latest as unset and can incorrectly default to the pinned action tag, so the action may not install “latest” when requested.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 2
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

install-dir should be validated to prevent newline injection into $GITHUB_PATH/$GITHUB_OUTPUT when exporting PATH and outputs.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

It introduces a new supply-chain-sensitive installation path plus changes release/CI workflows, which warrants final human review despite strong test coverage.

Review details

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

.github/workflows/release.yml:42

• The release workflow's paths filter includes tools/action/**, which means changing only tools/action/*_test.go will cut a new release and force-move the v0 tag even though neither the shipped action (action.yml + tools/action/setup.sh) nor the binary changed. That adds release noise and can advance the recommended @v0 pin for changes that don't affect consumers.

Consider narrowing the trigger to just the shipped action files (e.g. tools/action/setup.sh and action.yml). Note: this will require updating the corresponding gate in tools/action/manifest_test.go that currently expects tools/action/ to be present.

      - 'action.yml'
      - 'tools/action/**'

docs/INSTALL.md:28

• This sentence says “One step”, but the example YAML shows two steps (one uses: step to install, then a separate run: step to use the tool). Tweaking the wording avoids confusion for readers skimming the page.

One step, and the binary is on the `PATH` for the rest of the job:

• Files reviewed: 11/11 changed files
• Comments generated: 0 new
• Review effort level: Lite