docs(branch-protection): document --apply mode and admin-token caveat - #417
Merged
Merged
Conversation
branch-protection now has two modes: the unchanged default that emits the protection JSON for an operator to apply, and an opt-in --apply that PUTs the body to GitHub directly with a caller-supplied scoped token. Document the new --apply, --token, --repo, and --api-url flags with their env fallbacks, note that applying requires repo-admin (Administration: write) which the workflow GITHUB_TOKEN lacks, and prefer the env var over the flag to keep the token out of process args. Cross-reference the apply mode from the hardening guide. Signed-off-by: Joshua Temple <joshua.temple@stablekernel.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
1 participant
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
Documents the
cascade branch-protection --applymode added in #416, which shipped under-documented.Changes
branch-protectionsection to cover both modes (default emit-JSON vs--applydirect PUT), added an apply subsection, and expanded the flags table (--apply,--token,--repo,--branch,--api-urlwith their env fallbacks). Corrected two sentences that feat(branch-protection): add --apply to apply protection with a scoped token #416 made stale: the intro claim that cascade never calls the GitHub API, and the unconditional note that--branchonly labels the guidance.Caveat documented
Applying requires a token with repo-admin authority (Administration: write); the workflow GITHUB_TOKEN cannot do it, and the env var is preferred over the flag to keep the token out of process args and shell history.
Verification
Every documented flag and default verified against internal/branchprotection/command.go + apply.go. Default-mode description confirmed behavior-accurate (emit wrapper, no API call when --apply is absent). Docs-only; no Go changes.