docs: GitHub App setup guide for Codewhale Agent reviews #5707
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,89 @@ | ||
| # GitHub App Setup (Codewhale Agent reviews) | ||
|
|
||
| `codewhale review --pr N` writes an advisory code review of a pull request. With | ||
| `--post` (or from CI) the review is published to GitHub. Published reviews can | ||
| appear under two identities: | ||
|
|
||
| - the default token the CI job already has (`github.token`), or | ||
| - a dedicated **GitHub App** so the review shows as a bot — e.g. | ||
| `codewhale-agent[bot]` — instead of a personal account. | ||
|
|
||
| The App identity is optional. Nothing below is needed to run | ||
| `codewhale review --pr N` locally and print the report to your terminal. | ||
|
|
||
| Related docs: | ||
|
|
||
| - [Automatic Workflows](AUTOMATIC_WORKFLOWS.md) — the review workflow in context | ||
| - [Providers](PROVIDERS.md) — the model/key used to write the review | ||
| - [Receipts](RECEIPTS.md) — how posted reviews are anchored to a head SHA | ||
|
|
||
| ## One-time setup, five steps | ||
|
|
||
| You need owner access to the GitHub repository once. After these five steps | ||
| every non-draft pull request gets a Codewhale review posted as the App. | ||
|
|
||
| 1. **Create the App.** GitHub → *Settings → Developer settings → GitHub Apps → | ||
| New GitHub App*. Name it (e.g. `Codewhale Agent`), set a homepage URL, and | ||
| **uncheck Webhook → Active** — the review is pulled on PR events by Actions, | ||
| so no webhook is needed. | ||
| 2. **Grant two repository permissions.** | ||
| - *Pull requests* → **Read & write** (to post the review and inline comments) | ||
| - *Contents* → **Read-only** (to read the diff; read-only is enough — avoid | ||
| write unless you have another reason) | ||
| Choose *Only on this account*, then **Create GitHub App**. | ||
|
There was a problem hiding this comment.
When the target repository belongs to an organization but the App was created from the user's personal Developer settings as this sequence suggests, selecting Only on this account restricts installation to that personal account, so the organization repository cannot be selected in step 4 even if the user administers it. Distinguish personal and organization ownership here: create an organization-owned App from the organization's settings, or allow installation on other accounts and have the organization approve it. Useful? React with 👍 / 👎. |
||
| 3. **Download the private key.** On the App's page, *Private keys → Generate a | ||
| private key*. Keep the `.pem` file secret; it is the App's credential. | ||
| 4. **Install the App** on your account (*Install App* on the same page) and | ||
| select the repositories reviews should cover. | ||
| 5. **Add three repository settings.** GitHub → *Settings → Secrets and | ||
| variables → Actions*: | ||
|
|
||
| | Kind | Name | Value | | ||
| |----------|--------------------------|----------------------------------------| | ||
| | Variable | `CODEWHALE_APP_ID` | the App ID shown on the App's page | | ||
| | Secret | `CODEWHALE_APP_PRIVATE_KEY` | the full `.pem` file contents | | ||
| | Secret | `DEEPSEEK_API_KEY` | provider key for the review model (or the env var matching your provider; see [Providers](PROVIDERS.md)) | | ||
|
There was a problem hiding this comment.
When a user follows the parenthetical for another provider—for example, by creating AGENTS.md reference: AGENTS.md:L32-L32 Useful? React with 👍 / 👎. |
||
|
|
||
| `DEEPSEEK_API_KEY` is the only required one. Until it exists, the workflow | ||
| skips itself with a green notice — it is safe to merge the workflow before | ||
| finishing setup. Optional: variable `CODEWHALE_REVIEW_MODEL` overrides the | ||
| model (e.g. `deepseek-chat`). | ||
|
|
||
| ## How the pieces connect | ||
|
|
||
| `.github/workflows/codewhale-review.yml` runs on every non-draft PR. When | ||
|
There was a problem hiding this comment.
This says the workflow runs on every non-draft PR, but AGENTS.md reference: AGENTS.md:L3-L5 Useful? React with 👍 / 👎. |
||
| `CODEWHALE_APP_ID` **and** `CODEWHALE_APP_PRIVATE_KEY` are both present, the | ||
| job mints a short-lived installation token for the App | ||
| (`actions/create-github-app-token`) and hands it to the CLI as `GH_TOKEN`. | ||
| Otherwise it falls back to the workflow's own `github.token`. The CLI never | ||
| stores the token; each run mints a fresh one. | ||
|
|
||
| The review itself is one **COMMENT** review — a summary body plus inline line | ||
| comments anchored to the PR head SHA. It never approves or requests changes; | ||
| CODEOWNERS stays the human authority. | ||
|
|
||
| ## Running a review yourself | ||
|
|
||
| ```sh | ||
| # print a report locally (uses your configured provider key) | ||
| codewhale review --pr 1234 | ||
|
Comment on lines
+68
to
+69
There was a problem hiding this comment.
When a user follows this local example without Useful? React with 👍 / 👎. |
||
|
|
||
| # publish it to GitHub as whichever identity GH_TOKEN carries | ||
| codewhale review --pr 1234 --post | ||
| ``` | ||
|
|
||
| `GH_TOKEN` may be your `gh` CLI token (posts as you) or an App installation | ||
| token (posts as the App). The `--post` flag is always opt-in. | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| - **Review posts as you, not the bot.** The variable or the private-key secret | ||
| is missing/empty; the job silently falls back to `github.token`. Check both | ||
| names character-for-character. | ||
| - **Workflow logs "DEEPSEEK_API_KEY is not set — skipping".** Expected until | ||
| the provider secret exists. | ||
| - **App token step fails.** The `.pem` was regenerated after the secret was | ||
| set — paste the newest key into `CODEWHALE_APP_PRIVATE_KEY` again, and | ||
| confirm the App is actually installed on the repository. | ||
| - **Name already taken.** GitHub App names are global; pick another name. The | ||
| bot's display login is `<slug>[bot]`, derived from the name. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When this App is installed on a private repository, granting
Contents: Read-onlyexposes the entire repository even though the App token is not used for checkout—the workflow mints it only afteractions/checkoutat.github/workflows/codewhale-review.yml:46-58—and the CLI uses it only forgh pr view,gh pr diff`, repository metadata, and posting a pull-request review. Pull-request read/write plus the metadata permission implicit for GitHub Apps covers those operations, so remove this permission rather than expanding the impact of an App-key compromise.Useful? React with 👍 / 👎.