Skip to content

docs(configuration): document cascade's ownership of generated action pins - #473

Merged
joshua-temple merged 1 commit into
mainfrom
docs/pin-ownership-baseline
Jul 6, 2026
Merged

joshua-temple merged 1 commit into
mainfrom
docs/pin-ownership-baseline

Conversation

@joshua-temple

Copy link
Copy Markdown
Collaborator

Problem

The docs did not explain that the action pins in cascade-generated workflows are build output cascade owns. Users had no guidance on the supported way to change a pinned action, what happens when they hand-edit a generated pin, or the token and automerge implications of adopting an external pin.

Fix

Reworks the "Action pinning" section of configuration.md:

  • Frames generated workflows as build output whose pins cascade owns and reconciles; changing a pinned action is done through action_pins / pin_mode, and hand-edits to generated files are drift that regeneration overwrites.
  • Documents channel-switch semantics: an action_pins override moves that action off cascade's curated table and becomes the only retained state, with the trailing-pin staleness edge noted as deferred.
  • Demotes excluding generated paths from Dependabot to a non-engine fallback rather than the recommended posture.
  • Adds a forward-looking token permission set (recommending a GitHub App installation token or a fine-grained PAT).
  • States the automerge caveat plainly, and notes the manifest-pointer header as forward-looking only, not emitted today.

Verification

  • cd docs && npm run build succeeds (17 pages built).
  • Independent review passed.

Closes #439.

… pins

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
@joshua-temple
joshua-temple merged commit 4d3c4b3 into main Jul 6, 2026
17 checks passed
@joshua-temple
joshua-temple deleted the docs/pin-ownership-baseline branch July 6, 2026 00:44
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.

document Dependabot handling for cascade-generated workflows

1 participant