Repository navigation
Update Chainguard Actions overview for GA - #4029
Merged
matthewhelmke merged 8 commits intoOct 5, 2026
Merged
Conversation
✅ Deploy Preview for ornate-narwhal-088216 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
matthewhelmke
marked this pull request as draft
September 21, 2026 13:25
|
@matthewhelmke is attempting to deploy a commit to the Chainguard Team on Vercel. A member of the Team first needs to authorize it. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
matthewhelmke
marked this pull request as ready for review
September 23, 2026 13:06
maephillips
reviewed
Sep 23, 2026
Collaborator
Author
|
Do not merge until 2026-10-05 |
s-stumbo
approved these changes
Sep 24, 2026
matthewhelmke
force-pushed
the
actions-doc-updates-for-GA
branch
from
September 25, 2026 17:02
f4b5f27 to
73af60c
Compare
Add the hardening ruleset and transitive dependency behavior, and lead the setup path with the Guardener GitHub App (DOCS-204). - Document all seven hardening checks with their finding IDs, severities, and scope, matching the approved public rulebook - Add a transitive dependencies section covering what is hardened today and the two limits that remain - Restructure setup into an entitlement step and a Guardener GitHub App step - Correct the re-hardening bullet: a ruleset change re-evaluates every action in the catalog, not only affected ones - Correct the repository contents section. The hardened action lives on the version branches; main holds only metadata. The quick start example used @main, which cannot resolve. - Document the signed SLSA provenance attestation on each version branch - Add a section on referencing by version tag versus commit SHA - Add `chainctl actions discover --recursive` and `chainctl actions list` - Update the catalog size to more than 1,000 actions - Merge the duplicated request and report issue sections Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Corrects two substantive errors and adds the facts his review surfaced (DOCS-204). - Transitive dependencies: the nested-reference rewriting is implemented and enabled in production, not "in development" as previously written. The Linear states that conclusion rested on were stale. Reframed as rolling out, since no published action references a hardened counterpart yet, and added the three scope limits: composite actions only, exact-commit counterparts only, never when ambiguous. - Document the static pre-pass as its own group of checks. It emits finding IDs that aren't in the policy ruleset, and one of them, `static-inline-injection`, is the most common finding in the catalog, so a reader could previously hit an ID this page couldn't resolve. - State that the rebuild reproduces a JavaScript action's bundle rather than refreshing it, so a hardened release ships the dependency versions upstream shipped. Say plainly that dependency vulnerability management isn't part of hardening today. - Recommend pinning to a commit SHA paired with Dependabot or Renovate, replacing the neutral tradeoff. A commit SHA is the only immutable reference in the catalog; re-hardening moves even fully qualified patch tags. A pin with no bumper is the one configuration that strands you, so the page says so. - Explain that the entitlement doesn't gate consumption and can't, name the telemetry endpoint for egress allowlists, and note that an unreachable Chainguard cannot fail a customer's workflow. - Guardener: automated migration needs `migrate.enabled: true`, which the page previously implied came with installation. Link the permissions table for administrator approval, and clarify that beta means the interface may change, not that it isn't deployed. - Soften the attestation coverage claim and state that no customer-facing verification procedure exists yet. - Fix the `hardcoded-credentials` and `unpinned-uses` rows, which omitted `aws_secret` and understated the image-reference match. - telemetry.md: remove `actor` from the stored-metadata list. The service discards that claim, so the page over-reported what Chainguard keeps. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The documented output of `gh api ... commits/v47 --jq '.sha'` was `25a1eb5aa…`, captured before that tag moved. The current value is `4b4bd2ed9…`. The value was never wrong, it went stale — re-hardening a published version force-moves its tag, which is the behavior this page now documents. Printing a fixed digest as the answer undercuts that, so the example is updated and a note tells readers to run the command instead of copying the digest. Found while reviewing the catalog org README for DOCS-205, which carries the same stale value. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The page sent readers to the chainguard-actions README "for deeper technical details and some example migrations." That README is being trimmed to a landing page that points back here (DOCS-205), so the reference would have become circular. It now says what the org is actually good for: finding a specific action and reading its hardening report. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Rebasing onto main brought in two changes that this branch's new text predates: product naming corrected to the marketing style guide (chainguard-dev#4067) and internal links pointed at canonical paths (chainguard-dev#4068). - "Chainguard Guardener" becomes "Guardener". The style guide is explicit that the name is bare, with no article and no "Chainguard" prefix, and upstream applied that everywhere else. - The link to the Guardener permissions table was pointing at `#permissions-the-guardener-requests`. Upstream renamed that heading to "Permissions Guardener requests", so the anchor no longer resolved. The rebase itself picked up two upstream fixes automatically: the `chainctl` install link is now the canonical `/platform/` path, and "each Chainguard Action" is now "each hardened action", since the name is plural. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Under "Each hardened action:", the first bullet read "Pulls the upstream source at a pinned commit, reviews it using..." which made the action the thing doing the pulling and reviewing. The pipeline does that. Keeps the point of the earlier edit — not saying the action is "rebuilt from source", which reads as though the rebuild improves the bundle — and restores agreement with the stem and with the final bullet, which is also passive. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
matthewhelmke
force-pushed
the
actions-doc-updates-for-GA
branch
from
September 28, 2026 15:05
28621cb to
50e1242
Compare
matthewhelmke
added a commit
to matthewhelmke/.github
that referenced
this pull request
Oct 2, 2026
Mae reviewed the equivalent line on chainguard-dev/edu#4029 and noted that nothing is built or rebuilt for a YAML-only action — Chainguard takes the upstream code and hardens it. That page was fixed; this one was written from the earlier wording and kept "Is rebuilt from the upstream source", so the correction never reached it. Now matches the edu page word for word, which is the point of having one of these documents link to the other. The remaining mention of rebuilding is scoped to a JavaScript action's bundle, which does get rebuilt from the upstream lockfile. That sentence is the one establishing that the rebuild reproduces the bundle rather than refreshing it, so it stays. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The hook is a runs.pre script only in JavaScript actions. Composite actions run it as their first step, and Docker actions don't include it. Also moves the egress allowlist tip onto the telemetry page. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tylerpaxton
reviewed
Oct 2, 2026
tylerpaxton
left a comment
tylerpaxton
left a comment
Contributor
There was a problem hiding this comment.
pushed 06e9e99 to fix the telemetry hook description. it's a pre script on JS actions, the first step on composite actions, and Docker actions don't have it. also moved the egress allowlist tip to the telemetry page.
on tag vs SHA: we're recommending SHA pinning, so the suggestions below make the page consistent with that.
tylerpaxton
reviewed
Oct 2, 2026
tylerpaxton
reviewed
Oct 2, 2026
matthewhelmke
added a commit
that referenced
this pull request
Oct 5, 2026
## What this does Applies Tyler Paxton's review of the Chainguard Actions overview. He commented on [#4029](#4029) on 10-02; it merged on 10-05 before those comments were addressed, so this is the follow-up (DOCS-204). Nine requests, all applied. Three of them corrected factual errors on a page that is now live, which is the reason this is worth reviewing promptly rather than batching. ## Corrections **A hardened action's `dist/` bundle is not rebuilt.** The page said Chainguard rebuilds it, and that the rebuild reproduces rather than refreshes the contents. Verified against the catalog: the git blob SHA of `dist/index.js` in `tj-actions-changed-files@v47` and `actions-checkout@v6` is identical to upstream at the pinned commit, so the bundle is carried over verbatim. The conclusion the page drew was right — a hardened release ships the same dependency versions as upstream — but the stated mechanism wasn't. Mae Phillips raised this on the intro bullet during #4029 and Tyler caught the same error further down. **Digest pinning covers `runs.image`, not Dockerfile `FROM` lines.** The page described a single rule covering both. The image case is now specific: for `runs.using: docker` with a `docker://` image, the pipeline resolves the tag and rewrites the reference as `image:tag@sha256:<digest>`. Confirmed on `google-osv-scanner-action@v2.6.0`. **Nested actions are swapped for hardened copies, and that is live.** The page said references were pinned to upstream SHAs and described the swap as rolling out. In composite actions the reference now points at the hardened copy where one exists. Confirmed: `actions-upload-pages-artifact@v5.0.0` calls `chainguard-actions/actions-upload-artifact@92725eed # v7.0.0`. The three scope limits stay, because coverage still grows as more of the catalog is hardened. ## Pinning guidance SHA pinning now reads as the default rather than an option. The quick start shows a commit SHA with the tag as a comment instead of a bare version tag, and the migration step no longer frames pinning as conditional. ## Setup Guardener also reads an org-wide `.chainguard/actions.yaml` from the organization's `.github` repository, which matters for a section aimed at more than a repository or two. Both setup steps now say so and link the [org-level configuration reference](/chainguard/guardener/github/configuration/#organization-level-configuration-with-the-github-repository). The GitHub App is called the Chainguard App for GA, renamed on this page only. Eight other pages still say "Guardener GitHub App" and are a separate change. References to Guardener as the agent are unchanged, matching Tyler's own suggested wording. ## Removed "What the entitlement controls" is gone at Tyler's request. The egress-allowlist tip it carried already lives on the [telemetry page](/chainguard/actions/telemetry/). Dropping it exposed something that section had been correcting: the preceding line said the entitlement exists "to enable access to the hardened actions hosted at `github.com/chainguard-actions`", and those repositories are public. That line now states the step without characterizing what the entitlement gates, which avoids both the misleading claim and the explanation Tyler asked us not to publish. ## Testing `npm run build` completes clean and all pre-commit hooks pass, including the new page-weight check. Verified in the rendered output that every in-page anchor resolves — including the new `#replace-the-uses-line-in-each-workflow` cross-link — that the cross-page org-level configuration anchor exists, and that nothing links to the removed section. ## Not verified Tyler's observation that Dockerfile `FROM` lines are unchanged from upstream rests on his own check. Dockerfile-based actions are rare enough that none appeared in a 22-repository sample, so I could not reproduce it independently. It appears only in the scope line, not in the rules this PR rewrote. --- Created in collaboration with Claude Code running Claude Opus 5 on 2026-10-05. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Updates the Chainguard Actions overview for the 2026-10-06 GA launch (DOCS-204), and corrects two errors on the existing page.
The quick start's first code sample told readers to reference a hardened action as
chainguard-actions/<name>@main. That cannot resolve — there is no action definition onmain— so anyone following the published quick start got a workflow that failed at theuses:line.GA content
HARDENING.mdand their severities, matching the rulebook PMM approved for public use. The slide maps one-to-one ontochainguard-dev/guarded-actions/policy/checks/. Documents scope too: the checks readaction.ymland.github/workflows/, and skipdist/,vendor/,node_modules/, and test fixtures.uses:and image references pinned to immutable SHAs or digests, the action repo's own workflows held to the same ruleset, missing dependencies onboarded on request — and the two limits that remain.attestations/provenance.intoto.jsonl, the signed SLSA provenance envelope on every version branch. No page mentioned it.Corrections to the existing page
@maincannot resolve.mainholds onlyREADME.md,LICENSE_CHAINGUARD, andsource.json. Verified across 34 distinct repos with zero exceptions — 21 sampled evenly across the sorted org listing, the 11 oldest repos, and five named repos — checking each default branch foraction.yml,action.yaml, and a rootDockerfile. The example now uses a version tag, with a note warning against@main.HARDENING.mdandaction.ymlas main-branch files. They are on the version branches. Rewritten to distinguish the two, with a note to read the report on the branch you plan to use.chainctl actions discover --recursiveand its$GITHUB_TOKENrequirement, pluschainctl actions list. All were missing.Testing
npm run buildcompletes clean and all pre-commit hooks pass. Verified in the rendered output that the checks table produces all seven rows with the escaped pipe incurl ... | bashintact, and that both in-page anchors resolve against the generated heading IDs.Open
Two items sit with PMM and Product and do not block this PR: the transitive dependency scope, and whether to recommend a version tag or a SHA as the default. Both are recorded on DOCS-204.
Created in collaboration with Claude Code running Claude Opus 5 on 2026-09-21.