diff --git a/.github/cursor-review/README.md b/.github/cursor-review/README.md index cdaa3057..56cf2983 100644 --- a/.github/cursor-review/README.md +++ b/.github/cursor-review/README.md @@ -419,6 +419,7 @@ All optional except `workflows_ref` (required, no default) — pass them under | `rereview_command` | `''` (off) | A comment command, e.g. `/review`, asking for another round on the **same commit**. Empty leaves the same-commit dedupe absolute. Needs the SAME value on [`cursor-review-auto-label.yml`](../../docs/callers/cursor-review-auto-label.md) plus `issue_comment` in that caller's triggers: that half re-applies the label (removing it first, since adding a label already present raises no event), this half stops the dedupe from skipping the round it starts. Setting one alone is a silent no-op. The command must be the first token of the first line, and the commenter's association must be `OWNER`, `MEMBER` or `COLLABORATOR` — not the opted-in roster. The request must postdate the review it overrides, so one request buys one round; `max_rounds` still applies. Exists because the documented alternative cannot work: the consolidated review is `COMMENTED`, which GitHub will not dismiss. See [the setup guide](../../docs/callers/cursor-review.md#asking-for-another-round-on-the-same-commit). | | `max_rounds` | `5` | Per-PR review-round cap; `0` → none. Counts the posting identity's consolidated reviews since `needs-human-review` was last removed; at or over the cap the panel is skipped, the PR is labelled `needs-human-review`, one comment lists the latest round's open findings above the threshold, and the `approve_gate` output is `capped`. Fails open on a read error. See [the setup guide](../../docs/callers/cursor-review.md#round-cap-and-the-approve_gate-output). | | `runs_on` | `'"ubuntu-latest"'` | JSON-encoded `runs-on` (same shape as `cursor-review-auto-label.yml`'s) for the four credential-free heavy jobs only: `diff-size`, `preflight`, the `review` panel and `consolidate`. The gate, ledger, Slack notices and every job holding the App token or `pull-requests: write` stay on GitHub-hosted `ubuntu-latest`. Those four run models with unsandboxed shell over PR code, so use a self-hosted pool only if each job gets a fresh pod (fresh filesystem and `$HOME`), holds no cloud identity or token, and can't reach private networks or the metadata server. The image must be linux/x64 with bash, git, curl, jq, python3, gh, tar and GNU coreutils. | +| `approver_environment` | `''` | The caller-repo environment holding `APPROVER_TOKEN` (an environment secret, base-branch-only deployment policy), declared on `post-review`, `dismiss-stale-approval` and `auto-retry` only, and only under `pull_request_target`. Pair with a `pull_request_target` caller — see the [trust model](../../docs/callers/cursor-review.md#trust-model). | ### `workflows_ref` must equal the `uses:` pin diff --git a/.github/cursor-review/tests/test_workflow_job_isolation.py b/.github/cursor-review/tests/test_workflow_job_isolation.py index 16a4d5b9..14065ee9 100644 --- a/.github/cursor-review/tests/test_workflow_job_isolation.py +++ b/.github/cursor-review/tests/test_workflow_job_isolation.py @@ -441,6 +441,78 @@ def test_payload_is_handed_over_as_an_artifact(self): self.assertIn("name: cursor-review-consolidated", post) self.assertIn("actions/download-artifact@", post) + def test_environment_is_declared_only_on_the_approver_token_jobs(self): + # approver_environment confines APPROVER_TOKEN to a base-branch-only + # environment. Declaring it on a PR-checkout job would hand that + # environment's secrets to a job running models over PR code. + token_jobs = sorted( + name + for name, body in self.jobs.items() + if any("secrets.APPROVER_TOKEN" in line for line in code_lines(body)) + ) + self.assertEqual( + token_jobs, ["auto-retry", "dismiss-stale-approval", "post-review"] + ) + env_jobs = sorted( + name + for name, body in self.jobs.items() + if any(re.match(r"^ environment:", line) for line in code_lines(body)) + ) + self.assertEqual(env_jobs, token_jobs) + for name in env_jobs: + body = code_lines(self.jobs[name]) + self.assertIn(ENVIRONMENT_LINE, body, name) + self.assertFalse( + checks_out_pr_repo(self.jobs[name]), + f"`{name}` declares the approver environment and checks out PR code", + ) + approve = read_lines(APPROVE_WORKFLOW) + self.assertEqual( + [line for line in approve if re.match(r"^\s+environment:", line)], + [ENVIRONMENT_LINE], + ) + + def test_every_pr_checkout_pins_a_ref(self): + # Under pull_request_target actions/checkout defaults to the BASE + # branch, so a PR checkout with no `ref:` would review the wrong tree. + pinned = 0 + for name, body in self.jobs.items(): + for step in split_steps(body): + lines = outside_run_blocks(code_lines(step)) + if not any(CHECKOUT.match(line) for line in lines): + continue + if any( + (m := REPOSITORY.match(line)) and scalar(m.group(1)) == ASSETS_REPO + for line in lines + ): + continue + refs = [line for line in lines if re.match(r"^\s+ref:\s*\S", line)] + self.assertTrue(refs, f"`{name}` checks out PR code with no `ref:`") + # The head SHA, not `refs/pull//merge`: that ref is mutable + # between jobs and absent on a conflicted PR. + self.assertEqual( + [r.split("ref:", 1)[1].strip() for r in refs], + ["${{ github.event.pull_request.head.sha }}"], + name, + ) + pinned += 1 + self.assertGreaterEqual(pinned, 5) + + +def read_lines(path): + with open(path, encoding="utf-8") as f: + return f.read().split("\n") + + +# Declared only under pull_request_target: any other event runs on the PR's +# merge ref, which a base-branch-only deployment policy rejects. +ENVIRONMENT_LINE = ( + " environment: ${{ github.event_name == 'pull_request_target'" + " && inputs.approver_environment || '' }}" +) + +APPROVE_WORKFLOW = os.path.join(os.path.dirname(WORKFLOW), "cursor-approve.yml") + if __name__ == "__main__": unittest.main(verbosity=2) diff --git a/.github/workflows/cursor-approve.yml b/.github/workflows/cursor-approve.yml index 7b3c2fff..b3821dbb 100644 --- a/.github/workflows/cursor-approve.yml +++ b/.github/workflows/cursor-approve.yml @@ -56,6 +56,10 @@ name: Cursor approve # marked non-gating stop blocking auto-resolution, as # cursor-review's own decide does. Default `full`: a marked # thread blocks like any other (fail-closed) +# approver_environment the caller-repo environment holding APPROVER_TOKEN +# (an environment secret, deployment branches = the base +# branch only), declared on the `approve` job. Default '' = +# none. See docs/callers/cursor-review.md#trust-model. # prior_rounds 0..3 (default 0 = off): how many earlier rounds of each # axis's own verdicts it sees. decide writes them to the # card as one base64 sentinel line; start reads them back @@ -110,6 +114,13 @@ on: prior_rounds: type: number default: 0 + approver_environment: + description: >- + The caller-repo environment that holds APPROVER_TOKEN. With a + deployment-branch policy of the base branch only, the token is + unreachable from `pull_request` runs. Empty (default) = no environment. + type: string + default: '' secrets: APPROVER_TOKEN: required: false @@ -126,6 +137,11 @@ jobs: name: 'cursor-approve (${{ inputs.phase }})' runs-on: ubuntu-latest timeout-minutes: 10 + # The caller environment holding APPROVER_TOKEN; '' = none (the trust + # model in docs/callers/cursor-review.md#trust-model). Only under + # `pull_request_target`: any other event runs on `refs/pull//merge`, + # which a base-branch-only deployment policy rejects before a step runs. + environment: ${{ github.event_name == 'pull_request_target' && inputs.approver_environment || '' }} permissions: contents: read actions: read @@ -137,6 +153,8 @@ jobs: PHASE: ${{ inputs.phase }} PR_NUMBER: ${{ github.event.pull_request.number }} PRIOR_ROUNDS: ${{ inputs.prior_rounds }} + EVENT_NAME: ${{ github.event_name }} + APPROVER_ENVIRONMENT: ${{ inputs.approver_environment }} run: | case "$PHASE" in start|decide) ;; @@ -150,6 +168,20 @@ jobs: if [ -z "$PR_NUMBER" ]; then echo "::error::cursor-approve runs on a pull_request(_target) event only"; exit 1 fi + # Only `pull_request_target` loads the caller from the base branch; on + # any other event a PR can read APPROVER_TOKEN. Post no card and no + # approval as it — but still withdraw that identity's own marked + # approvals (`withdraw_only`), so one it posted earlier at this head + # does not keep satisfying branch protection. + if [ -n "$APPROVER_TOKEN" ] && [ "$EVENT_NAME" != "pull_request_target" ]; then + echo "::error::APPROVER_TOKEN on a '$EVENT_NAME' run is readable by any PR-head workflow, so this run posts no approval (it still withdraws earlier ones); call this reusable from pull_request_target with approver_environment (docs/callers/cursor-review.md#trust-model)" + echo "present=false" >> "$GITHUB_OUTPUT" + echo "withdraw_only=true" >> "$GITHUB_OUTPUT" + exit 0 + fi + if [ -n "$APPROVER_TOKEN" ] && [ -z "$APPROVER_ENVIRONMENT" ]; then + echo "::warning::APPROVER_TOKEN without approver_environment is a repo secret that any PR-head pull_request workflow can read; move it into a base-branch-only environment and pass approver_environment (docs/callers/cursor-review.md#trust-model)" + fi if [ -z "$APPROVER_TOKEN" ]; then echo "::warning::APPROVER_TOKEN is empty — cursor-approve posts no card and no approval (there is no fallback identity)." echo "present=false" >> "$GITHUB_OUTPUT" @@ -215,7 +247,7 @@ jobs: fi - name: Load cursor-approve scripts - if: steps.token.outputs.present == 'true' + if: steps.token.outputs.present == 'true' || steps.token.outputs.withdraw_only == 'true' uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: repository: Comfy-Org/github-workflows @@ -225,7 +257,7 @@ jobs: - name: Resolve the approver login id: login - if: steps.token.outputs.present == 'true' + if: steps.token.outputs.present == 'true' || steps.token.outputs.withdraw_only == 'true' env: GH_TOKEN: ${{ secrets.APPROVER_TOKEN }} # Captured, not inlined into the echo: `echo "login=$(...)"` discards the @@ -239,7 +271,9 @@ jobs: echo "login=$login" >> "$GITHUB_OUTPUT" - name: Withdraw approvals while the axes run - if: steps.token.outputs.present == 'true' && inputs.phase == 'start' + # Also, in either phase, on a trigger that may not approve (see the + # token step). + if: (steps.token.outputs.present == 'true' && inputs.phase == 'start') || steps.token.outputs.withdraw_only == 'true' env: GH_TOKEN: ${{ secrets.APPROVER_TOKEN }} LOGIN: ${{ steps.login.outputs.login }} diff --git a/.github/workflows/cursor-review.yml b/.github/workflows/cursor-review.yml index b11a3046..3ea0ecd0 100644 --- a/.github/workflows/cursor-review.yml +++ b/.github/workflows/cursor-review.yml @@ -42,7 +42,11 @@ name: Cursor Review (reusable) # # moment the last finding thread is resolved. Advisory callers # # (`blocking` unset) can keep the narrower label-only pair; see # # docs/callers/cursor-review.md for both shapes. -# pull_request: +# # `pull_request_target`, not `pull_request`, once APPROVER_TOKEN is in +# # play: the caller file then comes from the BASE branch, so a PR cannot +# # rewrite it to read the token (docs/callers/cursor-review.md#trust-model). +# # Plain `pull_request` still works and is fine without APPROVER_TOKEN. +# pull_request_target: # types: [opened, reopened, ready_for_review, synchronize, labeled, unlabeled] # pull_request_review_thread: # types: [resolved, unresolved] @@ -103,6 +107,9 @@ name: Cursor Review (reusable) # # see docs/callers/cursor-review.md for the full flow, including the # # pull_request_review_thread trigger that re-checks on thread resolution. # blocking: true +# # Optional, with APPROVER_TOKEN: the environment holding it as an +# # ENVIRONMENT secret, deployment branches = the base branch only. +# approver_environment: cursor-approver # secrets: # CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }} # SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }} @@ -612,6 +619,21 @@ on: type: string required: false default: '"ubuntu-latest"' + approver_environment: + description: >- + The caller-repo environment that holds APPROVER_TOKEN, declared as + `environment:` on exactly the jobs that read it (`post-review`, + `dismiss-stale-approval`, `auto-retry`), on `pull_request_target` + runs only. Give the environment a + deployment-branch policy of the base branch only and store + APPROVER_TOKEN as an ENVIRONMENT secret there (not a repo secret): + the token is then unreachable from `pull_request` runs, which a PR + head controls. Pair with a `pull_request_target` caller — see + docs/callers/cursor-review.md#trust-model. Empty (default) = no + environment, exactly as before. + type: string + required: false + default: '' secrets: CURSOR_API_KEY: description: Cursor API key for cursor-agent (the panel + judge models bill through it). @@ -747,7 +769,7 @@ concurrency: # # `inputs` is an allowed context in a called workflow's workflow-level # `concurrency:`, same as the `env:` block below. - group: cursor-review-reusable-${{ github.event.pull_request.number || github.ref }}-${{ ((inputs.review_label != '' && github.event.label.name == inputs.review_label) || github.event.label.name == 'skip-cursor-review' || (inputs.run_without_label && github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'reopened' || github.event.action == 'ready_for_review' || github.event.action == 'synchronize'))) && 'trigger' || format('label-{0}', github.event.label.name) }} + group: cursor-review-reusable-${{ github.event.pull_request.number || github.ref }}-${{ ((inputs.review_label != '' && github.event.label.name == inputs.review_label) || github.event.label.name == 'skip-cursor-review' || (inputs.run_without_label && (github.event_name == 'pull_request' || github.event_name == 'pull_request_target') && (github.event.action == 'opened' || github.event.action == 'reopened' || github.event.action == 'ready_for_review' || github.event.action == 'synchronize'))) && 'trigger' || format('label-{0}', github.event.label.name) }} cancel-in-progress: true # DIFF_SIZE_CAP / REVIEW_LABEL / JUDGE_MODEL / DIFF_EXCLUDES are mapped from @@ -860,6 +882,8 @@ jobs: GH_EVENT_ACTION: ${{ github.event.action }} HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }} BASE_REPO: ${{ github.repository }} + PR_NUMBER: ${{ github.event.pull_request.number }} + EVENT_NAME: ${{ github.event_name }} RUN_WITHOUT_LABEL: ${{ inputs.run_without_label }} PR_AUTHOR_TYPE: ${{ github.event.pull_request.user.type }} PR_AUTHOR: ${{ github.event.pull_request.user.login }} @@ -873,8 +897,13 @@ jobs: # neither analyze nor post, so skip cleanly instead of burning the # 8-cell matrix + judge and failing red on every external contribution. # (head.repo.full_name != github.repository is the cross-repo signal.) - if [ -n "$HEAD_REPO" ] && [ "$HEAD_REPO" != "$BASE_REPO" ]; then - echo "PR is from a fork ($HEAD_REPO != $BASE_REPO) — review needs secrets and write access a fork PR can't have. Skipping." + # Under a `pull_request_target` caller this skip is LOAD-BEARING, not + # just a saving: there a fork run DOES get secrets, and the panel runs + # unsandboxed models over the fork's code. + # Fail closed: on a PR event an EMPTY head repo (a deleted fork — its + # code is still on refs/pull//merge) skips too. + if [ -n "$PR_NUMBER" ] && [ "$HEAD_REPO" != "$BASE_REPO" ]; then + echo "PR is from a fork (${HEAD_REPO:-deleted fork} != $BASE_REPO) — review needs secrets and write access a fork PR can't have. Skipping." echo "should_run=false" >> "$GITHUB_OUTPUT" exit 0 fi @@ -886,6 +915,15 @@ jobs: exit 0 fi + # Under `pull_request_target` a Dependabot PR's run gets the repo's + # REAL secrets (not the Dependabot store), and the panel would run + # `--trust` agents holding them over upstream-authored content. + if [ "$EVENT_NAME" = "pull_request_target" ] && [ "$PR_AUTHOR" = "dependabot[bot]" ]; then + echo "Dependabot PR under pull_request_target — skipping the panel (it would run with the repo's real secrets)." + echo "should_run=false" >> "$GITHUB_OUTPUT" + exit 0 + fi + # Machine-generated PRs (bot author AND a configured branch prefix) # skip the panel: a pinned-SHA bump or a catalog refresh has nothing a # reviewer can judge, and each one otherwise costs a full matrix run. @@ -2758,8 +2796,14 @@ jobs: PY - name: Checkout PR repo + # Pinned to the PR head SHA, as `diff-size` and `review-anthropic-direct` + # are: under `pull_request_target` the default is the BASE branch, and + # `refs/pull//merge` is neither immutable (each job resolves it + # separately, and the test merge lags a push) nor present on a + # conflicted PR, which `pull_request_target` still runs on. uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ github.event.pull_request.head.sha }} fetch-depth: 0 persist-credentials: false @@ -4215,8 +4259,14 @@ jobs: contents: read steps: - name: Checkout PR repo + # Pinned to the PR head SHA, as `diff-size` and `review-anthropic-direct` + # are: under `pull_request_target` the default is the BASE branch, and + # `refs/pull//merge` is neither immutable (each job resolves it + # separately, and the test merge lags a push) nor present on a + # conflicted PR, which `pull_request_target` still runs on. uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ github.event.pull_request.head.sha }} fetch-depth: 0 persist-credentials: false @@ -4809,8 +4859,14 @@ jobs: judge_status: ${{ steps.consolidated.outputs.judge_status }} steps: - name: Checkout PR repo + # Pinned to the PR head SHA, as `diff-size` and `review-anthropic-direct` + # are: under `pull_request_target` the default is the BASE branch, and + # `refs/pull//merge` is neither immutable (each job resolves it + # separately, and the test merge lags a push) nor present on a + # conflicted PR, which `pull_request_target` still runs on. uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ github.event.pull_request.head.sha }} fetch-depth: 0 persist-credentials: false @@ -5326,6 +5382,12 @@ jobs: # already `needs:` it), for the round number on the status card decide # writes (BE-19489). needs: [gate, consolidate, ledger, diff-size, round-cap] + # The caller environment holding APPROVER_TOKEN (docs/callers/cursor-review.md#trust-model); + # '' = none. Only the APPROVER_TOKEN jobs declare it — never a job that + # checks out PR code — and only under `pull_request_target`: any other + # event runs on `refs/pull//merge`, which a base-branch-only deployment + # policy rejects before a step runs. + environment: ${{ github.event_name == 'pull_request_target' && inputs.approver_environment || '' }} # `!cancelled()` rather than `always()`, for the same reason # `over-cap-comment` documents at its own `if:`: the documented caller sets # `cancel-in-progress: true`, and `always()` runs a job even when the RUN is @@ -5809,7 +5871,31 @@ jobs: ROUND: ${{ needs.round-cap.outputs.next_round }} MAX_ROUNDS: ${{ needs.round-cap.outputs.max_rounds }} RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + EVENT_NAME: ${{ github.event_name }} + APPROVER_ENVIRONMENT: ${{ inputs.approver_environment }} run: | + # Trust model (docs/callers/cursor-review.md#trust-model): only + # `pull_request_target` loads the caller from the base branch. Every + # other event (`pull_request`, `pull_request_review_thread`, …) loads + # it from the PR, so a PR can read APPROVER_TOKEN there: such a round + # APPROVES nothing. It keeps the same identity, though, and goes + # through `--defer-approval`, so it still withdraws that identity's + # own earlier approvals and can still request changes — switching to + # another login would strand an approval the token already posted. + # With approver_environment set, a non-target run has no token at all + # (the environment is declared only under `pull_request_target`), and + # it must not approve under the fallback identity either. + if [ "$EVENT_NAME" != "pull_request_target" ]; then + if [ -n "$APPROVER_TOKEN" ]; then + echo "::error::APPROVER_TOKEN on a '$EVENT_NAME' run is readable by any PR-head workflow, so this round posts no approval (it still withdraws stale ones); call this reusable from pull_request_target with approver_environment (docs/callers/cursor-review.md#trust-model)" + DEFER_APPROVAL=true + elif [ -n "$APPROVER_ENVIRONMENT" ]; then + echo "::notice::approver_environment is declared only under pull_request_target, so this '$EVENT_NAME' run posts no approval; the next pull_request_target round decides." + DEFER_APPROVAL=true + fi + elif [ -n "$APPROVER_TOKEN" ] && [ -z "$APPROVER_ENVIRONMENT" ]; then + echo "::warning::APPROVER_TOKEN without approver_environment is a repo secret that any PR-head pull_request workflow can read; move it into a base-branch-only environment and pass approver_environment (docs/callers/cursor-review.md#trust-model)" + fi # Same identity precedence as `Dismiss stale auto-approval`: the login # passed here is the one whose earlier approvals an untrusted round # withdraws. @@ -5902,9 +5988,15 @@ jobs: # Open PRs only: a title edit on a merged PR must not try a dismissal. name: Dismiss stale auto-approval if: >- - ${{ github.event_name == 'pull_request' && + ${{ (github.event_name == 'pull_request' || github.event_name == 'pull_request_target') && github.event.pull_request.state == 'open' && github.event.pull_request.head.repo.full_name == github.repository }} + # The caller environment holding APPROVER_TOKEN (docs/callers/cursor-review.md#trust-model); + # '' = none. Only the APPROVER_TOKEN jobs declare it — never a job that + # checks out PR code — and only under `pull_request_target`: any other + # event runs on `refs/pull//merge`, which a base-branch-only deployment + # policy rejects before a step runs. + environment: ${{ github.event_name == 'pull_request_target' && inputs.approver_environment || '' }} runs-on: ubuntu-latest timeout-minutes: 5 permissions: @@ -6007,7 +6099,18 @@ jobs: # Empty = auto-approve is off: its standing requests for changes are # withdrawn, since no round will ever approve over them. THRESHOLD: ${{ inputs.approve_max_severity }} + EVENT_NAME: ${{ github.event_name }} + APPROVER_ENVIRONMENT: ${{ inputs.approver_environment }} run: | + # Trust model (docs/callers/cursor-review.md#trust-model). Like + # `Auto-approve decision` this step still ACTS as APPROVER_TOKEN under + # `pull_request`: it only withdraws that identity's own approvals, and + # dropping to another login would strand a stale approval it posted. + if [ -n "$APPROVER_TOKEN" ] && [ "$EVENT_NAME" != "pull_request_target" ]; then + echo "::error::APPROVER_TOKEN under a pull_request trigger is readable by any PR-head workflow; call this reusable from pull_request_target with approver_environment (docs/callers/cursor-review.md#trust-model)" + elif [ -n "$APPROVER_TOKEN" ] && [ "$EVENT_NAME" = "pull_request_target" ] && [ -z "$APPROVER_ENVIRONMENT" ]; then + echo "::warning::APPROVER_TOKEN without approver_environment is a repo secret that any PR-head pull_request workflow can read; move it into a base-branch-only environment and pass approver_environment (docs/callers/cursor-review.md#trust-model)" + fi # Same identity precedence as `Auto-approve decision`, so the login # whose reviews are dismissed is the login that posted them. if [ -n "$APPROVER_TOKEN" ]; then @@ -6492,7 +6595,7 @@ jobs: EVENT_NAME: ${{ github.event_name }} run: | if [ -z "$PR_NUMBER" ]; then - echo "::error::The blocking gate was triggered by '$EVENT_NAME', which carries no pull_request payload, so it cannot read this PR's review threads. Trigger cursor-review from pull_request / pull_request_review_thread events (see the blocking caller shape in docs/callers/cursor-review.md)." + echo "::error::The blocking gate was triggered by '$EVENT_NAME', which carries no pull_request payload, so it cannot read this PR's review threads. Trigger cursor-review from pull_request (or pull_request_target) / pull_request_review_thread events (see the blocking caller shape in docs/callers/cursor-review.md)." exit 1 fi @@ -6902,6 +7005,12 @@ jobs: name: Re-run the round (head moved) needs: [post-review, panel-integrity, blocking-gate, notify-complete] if: ${{ !cancelled() && needs.post-review.outputs.auto_retry == 'true' }} + # The caller environment holding APPROVER_TOKEN (docs/callers/cursor-review.md#trust-model); + # '' = none. Only the APPROVER_TOKEN jobs declare it — never a job that + # checks out PR code — and only under `pull_request_target`: any other + # event runs on `refs/pull//merge`, which a base-branch-only deployment + # policy rejects before a step runs. + environment: ${{ github.event_name == 'pull_request_target' && inputs.approver_environment || '' }} runs-on: ubuntu-latest timeout-minutes: 5 permissions: @@ -6990,7 +7099,19 @@ jobs: PR_NUMBER: ${{ github.event.pull_request.number }} REPO: ${{ github.repository }} REVIEW_LABEL: ${{ inputs.review_label }} + EVENT_NAME: ${{ github.event_name }} + APPROVER_ENVIRONMENT: ${{ inputs.approver_environment }} run: | + # Trust model (docs/callers/cursor-review.md#trust-model): only + # `pull_request_target` loads the caller from the base branch; on any + # other event a PR can read APPROVER_TOKEN — do not act as it. (A + # relabel approves nothing, so the fallback identity is fine here.) + if [ -n "$APPROVER_TOKEN" ] && [ "$EVENT_NAME" != "pull_request_target" ]; then + echo "::error::APPROVER_TOKEN on a '$EVENT_NAME' run is readable by any PR-head workflow; call this reusable from pull_request_target with approver_environment (docs/callers/cursor-review.md#trust-model)" + APPROVER_TOKEN="" + elif [ -n "$APPROVER_TOKEN" ] && [ -z "$APPROVER_ENVIRONMENT" ]; then + echo "::warning::APPROVER_TOKEN without approver_environment is a repo secret that any PR-head pull_request workflow can read; move it into a base-branch-only environment and pass approver_environment (docs/callers/cursor-review.md#trust-model)" + fi if [ -n "$APPROVER_TOKEN" ]; then export GH_TOKEN="$APPROVER_TOKEN" elif [ -n "$BOT_TOKEN" ]; then diff --git a/docs/callers/cursor-approve.md b/docs/callers/cursor-approve.md index a8f50a36..f049cba0 100644 --- a/docs/callers/cursor-approve.md +++ b/docs/callers/cursor-approve.md @@ -246,9 +246,25 @@ per-PR `concurrency:` group cursor-review's caller already carries: it cancels a older run when a newer one starts, so two runs never write the card or decide on the same PR at once. +Trigger it from `pull_request_target` and keep `APPROVER_TOKEN` in a +base-branch-only environment passed as `approver_environment` to cursor-review +and to BOTH cursor-approve phases — see cursor-review's +[trust model](cursor-review.md#trust-model). On any other event with +`APPROVER_TOKEN` set, both phases print an error, post no card and no approval, +and only withdraw that identity's own earlier approvals. That is also why there +is no `pull_request_review_thread` trigger here: its caller comes from the PR, +so it may not approve, and the next `pull_request_target` round decides. + ```yaml +on: + pull_request_target: + # `edited` is REQUIRED: a base retarget fires only `edited`, and without + # it no run reaches `dismiss-stale-approval` to withdraw the approval. + types: [opened, reopened, ready_for_review, synchronize, edited, labeled, unlabeled] + concurrency: - group: cursor-review-pr-${{ github.event.pull_request.number }} + # `edited` gets its own group so a title edit cannot cancel a running panel. + group: cursor-review-pr-${{ github.event.pull_request.number }}${{ github.event.action == 'edited' && '-edited' || '' }} cancel-in-progress: true jobs: @@ -258,6 +274,7 @@ jobs: workflows_ref: approve_max_severity: low defer_approval: true # only cursor-approve's decide approves + approver_environment: cursor-approver secrets: inherit approve-start: @@ -273,6 +290,7 @@ jobs: with: workflows_ref: phase: start + approver_environment: cursor-approver commit_sha: ${{ github.event.pull_request.head.sha }} axes: correctness,conformance round: ${{ needs.cursor-review.outputs.round }} @@ -312,6 +330,7 @@ jobs: with: workflows_ref: phase: decide + approver_environment: cursor-approver commit_sha: ${{ github.event.pull_request.head.sha }} axes: correctness,conformance max_yellow_axes: 0 @@ -413,6 +432,7 @@ rollup, if at all; telling which leg failed needs per-job conclusions | `poster_login` | `''` | Decide phase: the login cursor-review posts findings under — `[bot]` when it runs with `bot_app_id`, else `github-actions[bot]`. Empty → no thread is resolved. | | `approve_scope` | `full` | Decide phase: cursor-review's `approve_scope_effective` output. `delta` → an open above-threshold thread that round marked non-gating (*Outside this round's changes*) does not block resolving the at-or-below-threshold threads, exactly as cursor-review's own decide treats it; the marked thread itself is never resolved. `full` (or empty) → any open above-threshold thread, marked or not, blocks all resolution. Any other value warns and resolves as `full`. | | `prior_rounds` | `0` | 0–3. How many earlier rounds of its OWN verdicts each axis sees; `0` turns it off, and every prompt and card is then byte-identical to a caller that never set it. `1`–`3`: the decide phase records this round on the card, and the next round's start phase hands the last N rounds to the axes. Pass the SAME value to both phases and to every axis wrapper. See [Prior rounds](#prior-rounds). | +| `approver_environment` | `''` | The caller-repo environment holding `APPROVER_TOKEN` as an environment secret, declared on the `approve` job under `pull_request_target` only. With a base-branch-only deployment policy the token is unreachable from `pull_request` runs. Pass the same value to both phases. See cursor-review's [trust model](cursor-review.md#trust-model). | ## Axis inputs diff --git a/docs/callers/cursor-review.md b/docs/callers/cursor-review.md index c10f37ee..870bb3fd 100644 --- a/docs/callers/cursor-review.md +++ b/docs/callers/cursor-review.md @@ -142,6 +142,7 @@ pull-requests: write # posting the consolidated review (and, at the round cap, | `rereview_command` | `''` (off) | A comment command, e.g. `/review`, that asks for ANOTHER round on the **same commit**. Empty leaves the same-commit dedupe absolute. Set the same value on [`cursor-review-auto-label.yml`](cursor-review-auto-label.md) — that half turns the comment into the label event, this half stops the dedupe from skipping the round it starts; setting only one is a silent no-op. Authorized = an `OWNER` / `MEMBER` / `COLLABORATOR` association on the comment. One request buys one round, and `max_rounds` still applies. See [below](#asking-for-another-round-on-the-same-commit). | | `max_rounds` | `5` | Cap on review rounds per PR (`0` → no cap). At or over it, no panel runs: the PR is labelled `needs-human-review`, one comment lists the latest round's open findings above the threshold, and the `approve_gate` output is `capped`. Removing the label resets the count. See [round cap](#round-cap-and-the-approve_gate-output). | | `runs_on` | `'"ubuntu-latest"'` | JSON-encoded `runs-on` for `diff-size`, `preflight`, the `review` panel and `consolidate` only — the jobs that hold no write credential. Every other job stays on GitHub-hosted `ubuntu-latest`. A self-hosted pool is fine only if it is one-job-per-fresh-pod, identity-free and private-network-isolated (those jobs run models with shell over PR code), on linux/x64 with bash, git, curl, jq, python3, gh, tar and GNU coreutils. Empty falls back to the default, so `${{ vars.CURSOR_REVIEW_RUNS_ON }}` is safe while the variable is unset; e.g. `'["self-hosted", "linux", "x64"]'`. | +| `approver_environment` | `''` | The caller-repo environment that holds `APPROVER_TOKEN` (as an environment secret). Declared as `environment:` on the three jobs that read the token, only under `pull_request_target`, and on none that checks out PR code. With a deployment-branch policy of the base branch only, the token is unreachable from `pull_request` runs. Use with a `pull_request_target` caller — see the [trust model](#trust-model). Empty = no environment. | ## Running a model experiment @@ -705,7 +706,9 @@ without a PR: ```yaml on: - pull_request: + # `pull_request_target`, not `pull_request`: under `pull_request` the + # reusable refuses to act as APPROVER_TOKEN — see the trust model below. + pull_request_target: # `synchronize`, `reopened` and `edited` are REQUIRED with auto-approve: # they dismiss the bot's earlier approval when new commits land (`reopened` # carries a push made while the PR was closed) or the base is retargeted. @@ -716,10 +719,14 @@ jobs: with: workflows_ref: approve_max_severity: ${{ vars.CURSOR_APPROVE_MAX_SEVERITY }} + # Optional: approve as a user account (see below). Store the token as an + # ENVIRONMENT secret named exactly `APPROVER_TOKEN` in this environment + # (deployment branches = the base branch only; see the trust model). The + # jobs that declare the environment read that secret, not the caller's. + approver_environment: cursor-approver secrets: CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }} - # Optional: approve as a user account (see below). - APPROVER_TOKEN: ${{ secrets.CURSOR_APPROVER_TOKEN }} + APPROVER_TOKEN: ${{ secrets.APPROVER_TOKEN }} ``` **Trying it on a few authors first.** `approve_authors` limits auto-approve to @@ -907,37 +914,84 @@ concurrency: cancel-in-progress: true ``` -**Known residual: the caller can drop the trigger.** For `pull_request` events +**Known residual: the caller can drop the trigger.** Under `pull_request` GitHub runs the caller workflow from the PR's head, so a commit can remove -`synchronize` (or the whole caller) and no dismissal runs for it. Closing that -needs dismissal from base-controlled code — e.g. a separate -`pull_request_target` dismiss-only job that checks out nothing. Until then, -treat this the same way as the trust model below. +`synchronize` (or the whole caller) and no dismissal runs for it. Under +`pull_request_target` the caller comes from the BASE branch, so a PR cannot +drop its own dismissal — another reason to use the shape in the trust model below. **Pair it with `detect-unreviewed-merge`'s `ignore-approvers`.** Pass the approver identity there, or the bot's approval satisfies that SOC 2 audit and a PR merged with no human review files nothing. See [`detect-unreviewed-merge.md`](detect-unreviewed-merge.md#automated-approvers-ignore-approvers). -**Trust model — read before letting the approval count.** The approval is -only as strong as two things a PR author controls: - -- **Prompt injection.** Every signal `decide` gates on — the findings, the - panel's status, the judge's status — is model output over the PR's own diff. - The panel and judge run with the PR checked out, so a diff written to steer - them can produce a clean round, and that round approves. No check computed - outside those jobs can tell a genuinely clean diff from a convincing one. -- **The switch lives in the PR.** For `pull_request` events GitHub runs the - caller workflow from the PR's head, so a same-repo PR can add - `approve_max_severity` (and drop `synchronize`) in the very commit it wants - approved. A repo variable keeps an *admin's* kill switch out of PRs; it does - not stop a PR from editing the caller to ignore it. - -So enabling auto-approve makes this approval no stronger than **push access** -to the repo. Do not let it be the only review that satisfies a ruleset for code -that needs a human's eyes — in particular, think twice before giving it an -`APPROVER_TOKEN` that is a code owner. Fork PRs never reach it (the `gate` job -skips them). +### Trust model + +Read this before letting the approval count. Call cursor-review (and +cursor-approve) from **`pull_request_target`** and pass +**`approver_environment`**: + +1. Create a caller-repo environment (e.g. `cursor-approver`) whose + deployment-branch policy is the base branch only, and store + `APPROVER_TOKEN` there as an **environment** secret — delete the repo-level + secret. Only the jobs that read it (`post-review`, `dismiss-stale-approval`, + `auto-retry`, cursor-approve's `approve`) declare that environment, and + only on `pull_request_target` runs; no job that checks out PR code does. +2. **Public repositories:** check the repo's Actions policy insights first. + GitHub's default event policy blocks `pull_request_target` in public + repositories; it runs in evaluate mode today and is enforced for affected + repositories from November 2, 2026, so configure an Actions event policy + that allows it before switching. +3. Switch the caller's `pull_request:` trigger to `pull_request_target:` (same + `types:`) and set `approver_environment: cursor-approver`. Every PR checkout + pins the PR head SHA, so the panel browses the same tree whose diff it + reviews (not the base branch, `pull_request_target`'s default). + +Why: under `pull_request` GitHub runs the caller workflow from the PR's head, +so any same-repo PR can rewrite it — or add a new workflow — to read +`APPROVER_TOKEN`, or add `approve_max_severity` in the very commit it wants +approved. Under `pull_request_target` the caller comes from the base branch, and +the base-branch-only environment keeps the token out of every `pull_request` +run. With `APPROVER_TOKEN` set, the token steps enforce this: on any event +other than `pull_request_target` (`pull_request`, but also +`pull_request_review_thread`, whose caller likewise comes from the PR) they +print an `::error::` and **approve nothing**. They keep the token's identity +only to withdraw its own earlier approvals and post requests for changes, so +no approval it already posted is stranded. `auto-retry` drops to the fallback +identity; cursor-approve posts no card. Under `pull_request_target` with no +`approver_environment` they warn. Neither turns the posting job red. + +**Thread resolution does not approve in this shape.** A +`pull_request_review_thread` run gets no environment (its ref, +`refs/pull//merge`, would fail the deployment-branch policy), so it posts no +approval, under any identity. The blocking caller still re-checks threads on +resolution, but the approval waits for the next `pull_request_target` event (a +push, or re-applying the review label). + +- **Forks.** The `gate` job still skips cross-repo heads. Under + `pull_request_target` a fork run DOES get secrets, so that skip is + load-bearing: never remove it or widen it. +- **Dependabot.** `pull_request_target` runs triggered by Dependabot get the + repo's real secrets (not Dependabot's), so `gate` skips the panel on a + Dependabot-authored PR under `pull_request_target`. Skipping the job in the + caller with `if: github.actor != 'dependabot[bot]'` also saves the run. +- **Actions cache scope.** Under `pull_request_target` every job runs in the + base branch's context, including the `review`, `judge-direct` and + `consolidate` jobs that run `--trust` agents over PR text. A cache entry such + a job could write lands in the base branch's cache scope, which + default-branch workflows (releases, deploys) restore. Under `pull_request` it + stayed in `refs/pull//merge`. Do not restore caches in trusted base-branch + workflows without verifying their contents if this matters to you. +- **Prompt injection still applies.** Every signal `decide` gates on — the + findings, the panel's status, the judge's status — is model output over the + PR's own diff. A diff written to steer the panel can produce a clean round, + and that round approves. No check computed outside those jobs can tell a + genuinely clean diff from a convincing one. + +So even in this shape the approval is no stronger than **push access** to the +repo. Do not let it be the only review that satisfies a ruleset for code that +needs a human's eyes — think twice before giving it an `APPROVER_TOKEN` that is +a code owner. **Who approves.** `APPROVER_TOKEN` if set, else the `bot_app_id` App, else `github-actions[bot]`. A GitHub App cannot be a CODE OWNER, so on a ruleset with