Skip to content

docs(issues): ISSUE-701 accepts tags backed by immutable releases - #497

Merged
thomasboni merged 1 commit into
mainfrom
docs/421-immutable-release-tags
Oct 27, 2026
Merged

thomasboni merged 1 commit into
mainfrom
docs/421-immutable-release-tags

Conversation

@Exypte

@Exypte Exypte commented Oct 21, 2026

Copy link
Copy Markdown
Contributor

What type of PR is this?

docs

What this PR does / why we need it:

Documents the ISSUE-701 change in getplumber/plumber#567. A tag backed by an immutable GitHub release now counts as pinned, for step actions and reusable-workflow calls. Only the exact released tag qualifies. Still reported:

  • floating majors such as @v4 (no release behind them);
  • mutable releases;
  • branches;
  • a tag shadowed by a same-named branch.

The check fails closed: without a token, or when the release cannot be read, the reference is reported.

  • ISSUE-701 page (src/data/issues.ts):
    • the description says an immutable-release tag is accepted;
    • the remediation adds "reference the exact released tag" as an alternative to a SHA pin;
    • a new first tip covers which tags qualify (docker/build-push-action@v7.4.0 yes, @v7 no), the shadowing branch, the API call and token requirement, fail-closed, and the actionPinningResult.immutableReleaseRefs list with pinnedVia: immutable_release.
  • Control catalog line (controlCatalog.actionsMustBePinnedByCommitSha): one sentence on the exemption.
  • Controls configuration (/docs/cli/controls-configuration#actionsmustbepinnedbycommitsha): a paragraph on the exemption and the token it needs.
  • Plumber Score sample report: immutableReleaseRefs and metrics.actionRefsImmutableRelease added to the actionPinningResult sample, matching the new report shape.
  • GitHub CLI troubleshooting: a row explaining why an action pinned to an immutable release tag can still be reported, and what to do.

Which issue(s) this PR is related to:

getplumber/plumber#421, getplumber/plumber#567

Special notes for your reviewer:

Merge after getplumber/plumber#567 ships in a CLI release, so the pages don't describe behavior the published CLI doesn't have yet.

How was this tested?

  • Every documented behavior was checked against the implementation and tests in feat(control,github): ISSUE-701 accepts a tag backed by an immutable release plumber#567. That PR also has an e2e run on real actions (docker/build-push-action@v7.4.0, golangci/golangci-lint-action@v9.3.0 and a docker/github-builder reusable workflow accepted; @v7, @master, a mutable release and @v1 still reported; everything reported again with the GitHub API disabled).
  • src/data/issues.ts parses (TypeScript syntax check). No em dashes in the new copy.
  • The site build and lint run in this PR's CI.

AI usage disclosure:

YES. Written with Claude Code from the #567 implementation, then reviewed by the author.

🤖 Generated with Claude Code

getplumber/plumber#567 accepts a tag whose GitHub release is immutable
as pinned, for steps and reusable workflows. Only the exact released tag
qualifies; floating majors, mutable releases, branches and a tag shadowed
by a same-named branch are still reported, and without a token (or when
the release cannot be read) the reference is reported.

- ISSUE-701 page: description, remediation and a first tip on the
  exemption, its token requirement and immutableReleaseRefs.
- Control catalog line and controls configuration section.
- Plumber Score sample report: immutableReleaseRefs and
  actionRefsImmutableRelease in actionPinningResult.
- GitHub CLI troubleshooting: why an immutable tag can still be reported.
@github-actions

Copy link
Copy Markdown

Preview deployment for 1d785cd: https://getplumber-h5z3ibpkj-getplumber.vercel.app

@thomasboni
thomasboni merged commit f98bacf into main Oct 27, 2026
9 checks passed
@thomasboni
thomasboni deleted the docs/421-immutable-release-tags branch October 27, 2026 19:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants