| 1 | # GitHub PR reviews |
| 2 | |
| 3 | The root `action.yml` runs the existing `codewhale review` command with an |
| 4 | exact, checksummed release. It needs Node.js 22+, `gh`, Git, and a macOS or |
| 5 | Linux runner. It does not compile Codewhale or execute the PR's code. |
| 6 | |
| 7 | This source adds review mode. Autonomous mention/fix mode remains on the |
| 8 | hosted GitHub App path; this Action does not yet implement SHA-6706's mention |
| 9 | acceptance. No release tag containing this Action is claimed here: pin the |
| 10 | reviewed Action commit until a release containing it exists. CLI version and |
| 11 | Action revision are separate pins. |
| 12 | |
| 13 | ## Account setup |
| 14 | |
| 15 | Connect your provider and select the model in Codewhale. Create a dedicated |
| 16 | account machine key with `account:read`, `agent:run` and `models:infer`, and |
| 17 | save it as the repository Actions secret `CODEWHALE_API_KEY`. |
| 18 | |
| 19 | Set repository variable `CODEWHALE_REVIEW_MODEL` to the exact `provider/model` |
| 20 | ID from the account's authenticated model catalog. This pins the account |
| 21 | selection explicitly: today's machine preflight exposes provider readiness, |
| 22 | not the selected model ID. Updating the account selection alone does not |
| 23 | update this variable. Do not substitute a guessed provider default or copy |
| 24 | the account key into a vendor key variable. |
| 25 | |
| 26 | Add `.github/workflows/codewhale.yml`, replacing `ACTION_COMMIT_SHA` with the |
| 27 | reviewed 40-character commit containing this Action: |
| 28 | |
| 29 | ```yaml |
| 30 | name: Codewhale review |
| 31 | on: |
| 32 | pull_request: |
| 33 | types: [opened, synchronize, reopened, ready_for_review] |
| 34 | workflow_dispatch: |
| 35 | inputs: |
| 36 | pr-number: |
| 37 | description: Same-repository PR number |
| 38 | required: true |
| 39 | type: string |
| 40 | permissions: |
| 41 | contents: read |
| 42 | pull-requests: write |
| 43 | concurrency: |
| 44 | group: codewhale-review-${{ github.event.pull_request.number || inputs.pr-number }} |
| 45 | cancel-in-progress: true |
| 46 | jobs: |
| 47 | review: |
| 48 | runs-on: ubuntu-latest |
| 49 | timeout-minutes: 25 |
| 50 | steps: |
| 51 | - uses: actions/setup-node@v7 |
| 52 | with: |
| 53 | node-version: '22' |
| 54 | - uses: codewhale-hq/CodeWhale@ACTION_COMMIT_SHA |
| 55 | id: review |
| 56 | with: |
| 57 | version: v0.10.0 |
| 58 | model: ${{ vars.CODEWHALE_REVIEW_MODEL }} |
| 59 | pr-number: ${{ inputs.pr-number }} |
| 60 | env: |
| 61 | CODEWHALE_API_KEY: ${{ (github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository) && secrets.CODEWHALE_API_KEY || '' }} |
| 62 | - uses: actions/upload-artifact@v7 |
| 63 | if: always() && steps.review.outputs.receipt != '' |
| 64 | with: |
| 65 | name: codewhale-review-${{ github.run_id }}-${{ github.run_attempt }} |
| 66 | path: ${{ steps.review.outputs.receipt }} |
| 67 | retention-days: 14 |
| 68 | ``` |
| 69 | |
| 70 | No repository checkout is needed. To post as your own GitHub App, supply an |
| 71 | installation token as `github-token`; see [App identity setup](GITHUB_APP.md). |
| 72 | Never use `pull_request_target` with this Action. Fork PRs and drafts are |
| 73 | ineligible even on a manual run. A skipped event is not a clean review. |
| 74 | |
| 75 | For BYOK, set `provider` explicitly (`deepseek`, `anthropic`, `openrouter`, |
| 76 | `zai`, or `modelstudio-token-plan`), set its exact `model`, and pass only the |
| 77 | matching provider secret in `env`. Omit `CODEWHALE_API_KEY`. The Action never |
| 78 | chooses a different credential after an authentication or payment failure. |
| 79 | |
| 80 | ## Bounds and evidence |
| 81 | |
| 82 | | Input | Default | Meaning | |
| 83 | | --- | --- | --- | |
| 84 | | `version` | Required | Exact released CLI tag, never `latest` | |
| 85 | | `provider` | `codewhale` | Account relay or explicit BYOK | |
| 86 | | `model` | Required | Exact model ID; account mode uses `provider/model` | |
| 87 | | `max-chars` | 200000 | Complete diff characters per pass, maximum 8388608 | |
| 88 | | `max-passes` | 1 | Complete ordered passes, maximum 64 | |
| 89 | | `max-output-tokens` | CLI automatic | Optional per-pass ceiling, 8192–1000000 | |
| 90 | | `timeout-seconds` | 600 | Model/publication deadline, 30–1200 | |
| 91 | | `post` | `true` | `false` produces a receipt without publishing | |
| 92 | |
| 93 | These are input, output, and time bounds, not a dollar guarantee. Model prices |
| 94 | and reasoning accounting vary. Raising the pass count authorizes more model |
| 95 | requests. The Action never retries inference automatically. Do not enable it |
| 96 | without setting the desired review scope and spend limits for the account. |
| 97 | |
| 98 | Outputs are `outcome`, `receipt` (absolute JSON path), and `pr-url`. The |
| 99 | receipt contains the pinned revision, route, limits, publication state, |
| 100 | completion counts and reported token usage. It excludes raw model output, |
| 101 | provider errors, PR text and credentials. Provider token accounting can be |
| 102 | absent. A runner shutdown before the receipt is written has no completion |
| 103 | receipt and must not be counted as a clean review. |
| 104 | |
| 105 | The CLI validates complete diff coverage and checks current revision before |
| 106 | publication. It reads bounded source excerpts from pinned Git blobs, without |
| 107 | running tests or investigating arbitrary unchanged callers. “Reviewed clean” |
| 108 | means the configured review completed with zero reported issues; it is not |
| 109 | proof that the PR contains no bugs. |
| 110 | |
| 111 | ## Outcomes and recovery |
| 112 | |
| 113 | | Outcome | Meaning / next action | |
| 114 | | --- | --- | |
| 115 | | `reviewed_clean` | Complete model review with zero reported issues | |
| 116 | | `reviewed_with_findings` | Complete model review; findings remain advisory | |
| 117 | | `configuration_missing` | Check the exact release/model, key presence, route and input bounds | |
| 118 | | `failed` | No complete review receipt; check account readiness, provider balance, release assets and GitHub access | |
| 119 | | `incomplete` | Coverage was incomplete; inspect the PR and revise scope or limits | |
| 120 | | `publication_uncertain` | Check the PR before any retry; publication may have succeeded | |
| 121 | | `superseded` | PR revision changed; run against the current head | |
| 122 | | `not_eligible` | Fork, draft, closed PR or unsupported event; no model run | |
| 123 | |
| 124 | Failures fail the optional Actions job; do not make it a required merge check |
| 125 | unless that is your repository policy. A provider failure is not a negative |
| 126 | verdict about the PR. No additional failure comment is posted. |
| 127 | |
| 128 | After repairing setup, use “Run workflow” with a PR number. Enabling a disabled |
| 129 | workflow does not replay old events. Manual reruns can publish another review: |
| 130 | cross-run publication deduplication is not implemented in this Action. Check |
| 131 | GitHub first, especially after a timeout or cancellation. Recovery is proved |
| 132 | by a complete receipt for the current head plus the intended publication, |
| 133 | not by workflow enablement alone. |
| 134 |