Repository navigation
Remove Administration permission requirement from safe-output branch checks - #76264
Conversation
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
|
✅ Test Quality Sentinel completed test quality analysis. Test Quality SentinelOutcome: The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible. Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.
|
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. See the comment below for the result and any generated ADR draft. Design Decision Gate 🏗️Outcome: The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible. Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.
|
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ Matt Pocock Skills ReviewerOutcome: The agent completed and reported one or more actions. The no-op output is a completion signal, not a claim that no action was taken. Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.
|
|
✅ PR Specification Reviewer completed successfully!
|
|
✅ PR Code Quality Reviewer completed the code quality review.
|
|
✅ Ponytail Reviewer completed successfully! Ponytail ReviewerOutcome: The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible. Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.
|
There was a problem hiding this comment.
Review completed: no actionable correctness, security, or maintainability issues found in the changed lines. The GraphQL replacement is fail-closed and is covered by updated regression tests.
🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt50 · ~2 AIC · ⌖ ~1 AIC · ⊞ 1.6K
Comment /review to run again
There was a problem hiding this comment.
Reviewed head c9e1e2aa204b5e8a1628e57f7fa79a2620f9c4d4 against the applicable safe-output contracts.
Blocking finding: docs/adr/28365-optional-branch-protection-check-for-push-to-pull-request-branch.md §Branch Protection Check Configuration, requirement 2, normatively requires the enabled/default handler to call GET /repos/{owner}/{repo}/branches/{branch}/protection. The PR changes the implementation and reference documentation to use GraphQL Ref.refUpdateRule instead, without updating or superseding that MUST requirement. The regression tests confirm the new behavior but do not establish conformance to the existing ADR. Please restore the required REST call or provide an approved contract update/migration and corresponding conformance evidence.
Applicable documents: safe-outputs specification v1.29.21 (push_to_pull_request_branch section) and ADR-28365. No specification files were edited or synchronized. Review coverage is limited to the captured PR diff and local contract documents; the base commit object was unavailable locally for a pre-change git show.
Generated by PR Specification Reviewer for #76264 · copilot · gpt50 · ~3 AIC · ⌖ ~2 AIC · ⊞ 1.7K
Comment /review-specs to run again
| When `check-branch-protection: false` is set, the branch protection pre-flight check is skipped. By default (`true`), the handler calls `GET /repos/{owner}/{repo}/branches/{branch}` and checks the `protected` flag before pushing. Branches protected by classic branch protection or restrictive rulesets are rejected, even when the proposed push would satisfy the ruleset (for example, by using a signed commit). | ||
|
|
||
| The sole exception is a non-default branch whose metadata explicitly disables classic protection, whose complete list of active rules contains only `copilot_code_review`, and whose classic protection endpoint explicitly reports `Branch not protected`. Automatic Copilot review does not restrict pushes. Rules are read page by page; unknown or mixed rule types, missing metadata, an empty initial response, an incomplete rules list, or any failed rules query leave the push blocked. Branch metadata may use `contents: read`; [active branch rules](https://docs.github.com/en/rest/repos/rules#get-rules-for-a-branch) require `Metadata: read`, while [classic-protection confirmation](https://docs.github.com/en/rest/branches/branch-protection#get-branch-protection) requires `Administration: read` for fine-grained tokens. `GITHUB_TOKEN` cannot provide `Administration` permission. If these reads are unavailable, the branch remains blocked without requesting broader credentials. No classic-protection lookup is needed for an unprotected branch. | ||
| The sole exception is a non-default branch whose metadata explicitly disables classic protection, whose complete list of active rules contains only `copilot_code_review`, and whose GraphQL `Ref.refUpdateRule` is explicitly `null`. Automatic Copilot review does not restrict pushes. Rules are read page by page; unknown or mixed rule types, missing metadata, an empty initial response, an incomplete rules list, or any failed rules query leave the push blocked. Branch metadata may use `contents: read`; [active branch rules](https://docs.github.com/en/rest/repos/rules#get-rules-for-a-branch) require `Metadata: read`, while [classic-protection confirmation](https://docs.github.com/en/graphql/reference/git#ref) uses `refUpdateRule`, which is viewable by non-admins and does not require `Administration: read`. If these reads are unavailable, the branch remains blocked without requesting broader credentials. No classic-protection lookup is needed for an unprotected branch. |
There was a problem hiding this comment.
This documents and implements a behavior that conflicts with the existing normative ADR contract. ADR-28365 §Branch Protection Check Configuration, requirement 2 (docs/adr/28365-optional-branch-protection-check-for-push-to-pull-request-branch.md:59) requires the enabled/default check to call GET /repos/{owner}/{repo}/branches/{branch}/protection; this PR replaces that call with GraphQL Ref.refUpdateRule. Because the ADR explicitly marks the REST call as MUST, please either restore conformance or provide an approved contract update/migration with conformance evidence. Do not treat this reference-doc edit alone as synchronizing the normative requirement.
There was a problem hiding this comment.
Updated and accepted ADR-28365 to replace the classic-protection REST requirement with GraphQL Ref.refUpdateRule; it now specifies explicit-null and fail-closed behavior and maps conformance to the regression tests. Commit: 208331a.
There was a problem hiding this comment.
🟡 Changes recommended
Stale guidance in the schema, code, and generated documentation may lead users to disable the branch-protection pre-flight guard unnecessarily.
1 open issue
What changed in this PR
Replaces the classic branch-protection lookup in safe-output push checks with GraphQL, removing the Administration: read requirement while preserving existing push safeguards.
Changes:
- Uses
Ref.refUpdateRule, accepting only explicitnullas absence of classic protection. - Updates regression tests for GraphQL responses and fail-closed handling.
- Documents the replacement API and its permission requirements.
| File | Description |
|---|---|
docs/src/content/docs/reference/safe-outputs-pull-requests.md |
Documents GraphQL protection checks and permissions. |
actions/setup/js/push_to_pull_request_branch.test.cjs |
Updates push-handler regression cases for GraphQL. |
actions/setup/js/pr_helpers.test.cjs |
Covers absent protection, existing protection, errors, and incomplete responses. |
actions/setup/js/pr_helpers.cjs |
Replaces the REST protection lookup with GraphQL. |
Review effort: Max (auto)
| When `check-branch-protection: false` is set, the branch protection pre-flight check is skipped. By default (`true`), the handler calls `GET /repos/{owner}/{repo}/branches/{branch}` and checks the `protected` flag before pushing. Branches protected by classic branch protection or restrictive rulesets are rejected, even when the proposed push would satisfy the ruleset (for example, by using a signed commit). | ||
|
|
||
| The sole exception is a non-default branch whose metadata explicitly disables classic protection, whose complete list of active rules contains only `copilot_code_review`, and whose classic protection endpoint explicitly reports `Branch not protected`. Automatic Copilot review does not restrict pushes. Rules are read page by page; unknown or mixed rule types, missing metadata, an empty initial response, an incomplete rules list, or any failed rules query leave the push blocked. Branch metadata may use `contents: read`; [active branch rules](https://docs.github.com/en/rest/repos/rules#get-rules-for-a-branch) require `Metadata: read`, while [classic-protection confirmation](https://docs.github.com/en/rest/branches/branch-protection#get-branch-protection) requires `Administration: read` for fine-grained tokens. `GITHUB_TOKEN` cannot provide `Administration` permission. If these reads are unavailable, the branch remains blocked without requesting broader credentials. No classic-protection lookup is needed for an unprotected branch. | ||
| The sole exception is a non-default branch whose metadata explicitly disables classic protection, whose complete list of active rules contains only `copilot_code_review`, and whose GraphQL `Ref.refUpdateRule` is explicitly `null`. Automatic Copilot review does not restrict pushes. Rules are read page by page; unknown or mixed rule types, missing metadata, an empty initial response, an incomplete rules list, or any failed rules query leave the push blocked. Branch metadata may use `contents: read`; [active branch rules](https://docs.github.com/en/rest/repos/rules#get-rules-for-a-branch) require `Metadata: read`, while [classic-protection confirmation](https://docs.github.com/en/graphql/reference/git#ref) uses `refUpdateRule`, which is viewable by non-admins and does not require `Administration: read`. If these reads are unavailable, the branch remains blocked without requesting broader credentials. No classic-protection lookup is needed for an unprotected branch. |
There was a problem hiding this comment.
Removed the stale advice from the schema and Go configuration comment, then updated the generated frontmatter reference so it describes the GraphQL check and no longer suggests disabling it to avoid Administration: read. Commit: 208331a.
|
@copilot update spec to reflect using graphql route |
|
@copilot run pr-finisher skill |
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /diagnosing-bugs and /tdd to a small, focused change. The GraphQL swap is sound and fail-closed handling is preserved. Requesting a docs-link check before merge.
📋 Key Themes & Highlights
Key Themes
- Unverified docs anchor: the new
graphql/reference/git#reflink insafe-outputs-pull-requests.mdshould be checked (see inline comment). - Query semantics not exercised: the unit tests mock
graphql, so theref(qualifiedName: "refs/heads/...")lookup is not validated against the live API. A live check, or a note in the PR, would close that gap. - Out-of-scope follow-up:
actions/setup/js/merge_pull_request.cjs(getBranchPolicy, ~line 375) still callsrepos.getBranchProtection, which needsAdministration: read. The PR scope is safe-output branch checks, so this is not blocking, but the same problem remains on the merge path.
Positive Highlights
- ✅ Accepting only an explicit
nullas "no classic protection" keeps the check fail-closed.undefined, missingref(non-existent branch), and GraphQL errors all block the push. - ✅ The new tests cover incomplete GraphQL responses (
undefined,null,{}, and each missing nesting level) and assertgetBranchProtectionis no longer called. - ✅ Error-path tests were updated to match the new source of truth rather than deleted.
Verification Limits
- I could not run the vitest suites:
npm cifailed on a registry TLS certificate error in this sandbox, so the test results are unverified. - I also could not fetch the GraphQL docs to confirm the anchor.
- I classified the change directly rather than invoking
pr-triage.
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · copilot · routed: haiku55 xhigh · ~6 AIC · ⌖ ~2 AIC · ⊞ 6.3K
Comment /matt to run again
| When `check-branch-protection: false` is set, the branch protection pre-flight check is skipped. By default (`true`), the handler calls `GET /repos/{owner}/{repo}/branches/{branch}` and checks the `protected` flag before pushing. Branches protected by classic branch protection or restrictive rulesets are rejected, even when the proposed push would satisfy the ruleset (for example, by using a signed commit). | ||
|
|
||
| The sole exception is a non-default branch whose metadata explicitly disables classic protection, whose complete list of active rules contains only `copilot_code_review`, and whose classic protection endpoint explicitly reports `Branch not protected`. Automatic Copilot review does not restrict pushes. Rules are read page by page; unknown or mixed rule types, missing metadata, an empty initial response, an incomplete rules list, or any failed rules query leave the push blocked. Branch metadata may use `contents: read`; [active branch rules](https://docs.github.com/en/rest/repos/rules#get-rules-for-a-branch) require `Metadata: read`, while [classic-protection confirmation](https://docs.github.com/en/rest/branches/branch-protection#get-branch-protection) requires `Administration: read` for fine-grained tokens. `GITHUB_TOKEN` cannot provide `Administration` permission. If these reads are unavailable, the branch remains blocked without requesting broader credentials. No classic-protection lookup is needed for an unprotected branch. | ||
| The sole exception is a non-default branch whose metadata explicitly disables classic protection, whose complete list of active rules contains only `copilot_code_review`, and whose GraphQL `Ref.refUpdateRule` is explicitly `null`. Automatic Copilot review does not restrict pushes. Rules are read page by page; unknown or mixed rule types, missing metadata, an empty initial response, an incomplete rules list, or any failed rules query leave the push blocked. Branch metadata may use `contents: read`; [active branch rules](https://docs.github.com/en/rest/repos/rules#get-rules-for-a-branch) require `Metadata: read`, while [classic-protection confirmation](https://docs.github.com/en/graphql/reference/git#ref) uses `refUpdateRule`, which is viewable by non-admins and does not require `Administration: read`. If these reads are unavailable, the branch remains blocked without requesting broader credentials. No classic-protection lookup is needed for an unprotected branch. |
There was a problem hiding this comment.
[/diagnosing-bugs] Verify this docs link before merging. graphql/reference/git#ref does not look like the page that documents the GraphQL Ref object, which lives under reference/objects. I could not reach docs.github.com from this sandbox to confirm. Please check that the anchor resolves and that refUpdateRule is documented as viewable without admin access.
💡 Suggested link
https://docs.github.com/en/graphql/reference/objects#ref
@copilot please address this.
There was a problem hiding this comment.
Verified the official GraphQL Git reference: the Ref type documents refUpdateRule as branch protection rules viewable by non-admins. The /graphql/reference/objects#ref suggestion redirects to the general reference index, so I retained /graphql/reference/git#ref and clarified the link label.
| } | ||
| if (classicStatus !== 404 || classicMessage !== "Branch not protected") throw classicError; | ||
| // refUpdateRule exposes classic protection to non-admins. | ||
| const result = await githubClient.graphql( |
There was a problem hiding this comment.
Wrapped the idempotent GraphQL protection read with the shared withRetry rate-limit retry policy and added a transient-503 regression test. Commit: 208331a.
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Added the safe-outputs specification requirements for the GraphQL |
Ran the PR finisher pass, addressed the actionable feedback, and pushed |
|
🎉 This pull request is included in a new release. Release: |

Safe-output branch checks currently use a classic-protection endpoint requiring
Administration: read, whichGITHUB_TOKENcannot provide. This change replaces that lookup without changing other push behavior.Ref.refUpdateRule, viewable by non-admins, instead of RESTgetBranchProtection.nullas absence of classic protection; retain existing default-branch guards, ruleset checks, and fail-closed handling.