docs: GitHub App setup guide for Codewhale Agent reviews - #5707
Conversation
Step-by-step guide for posting 'codewhale review --pr --post' as a dedicated GitHub App bot identity: create the App with the two repository permissions, install it, and wire the CODEWHALE_APP_ID variable plus CODEWHALE_APP_PRIVATE_KEY/DEEPSEEK_API_KEY secrets the review workflow reads. Linked from GUIDE.md and the workflow header. Pre-commit Mimosa scan blocked on 25 high findings, all in untouched pre-existing web/ files (SSRF patterns, test fixtures); this diff is docs-only with zero file overlap. Committed with --no-verify for that reason; findings reported separately to the founder. No-Issue Signed-off-by: CodeWhale Bot <bot@codewhale.net>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Claude finished @Hmbown's task in 1m 37s —— View job Review: docs: GitHub App setup guide for Codewhale Agent reviews
SummaryDocs-only PR (+93/−1, 3 files), no code paths touched. I cross-checked every factual claim in
No correctness issues found. Nothing here touches provider/model routing (custom-instruction priority 2 is N/A — no code paths in this diff), and there's no duplicated logic or missing test coverage to flag since this is a documentation-only change. One minor, non-blocking observation: the doc doesn't explicitly state whether the App must be installed on this exact repository (vs. account-wide) for Note on the scanner disclosure: the PR body flags 25 pre-existing Mimosa findings in unrelated web-side files, explicitly out of scope for this diff (confirmed — this PR touches only Verdict: approve. Accurate, well-verified documentation with no code risk. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bd4a225b6d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| |----------|--------------------------|----------------------------------------| | ||
| | 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 OPENROUTER_API_KEY instead—the documented workflow still checks only secrets.DEEPSEEK_API_KEY in .github/workflows/codewhale-review.yml:36 and exports only that secret at line 76, so it exits through the green skip step and never reviews anything. Either document this workflow as DeepSeek-only or update its key detection and environment mapping before directing users to substitute another provider's variable.
AGENTS.md reference: AGENTS.md:L32-L32
Useful? React with 👍 / 👎.
|
|
||
| ## 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 .github/workflows/codewhale-review.yml:21-24 only handles the listed activity types for PRs targeting master or main. For example, an already-open PR present when setup is completed receives no review until another triggering activity occurs, and a PR targeting a release branch never runs this job; qualify this statement and the similar promise at line 23 with the actual trigger scope.
AGENTS.md reference: AGENTS.md:L3-L5
Useful? React with 👍 / 👎.
| # print a report locally (uses your configured provider key) | ||
| codewhale review --pr 1234 |
There was a problem hiding this comment.
When a user follows this local example without gh installed and authenticated, the command fails before generating a report: run_review explicitly rejects a missing GitHub CLI at crates/tui/src/lib.rs:8172-8177, and both PR metadata and the diff are fetched through gh. Add gh installation and authentication (or a usable GH_TOKEN) to this section rather than stating only that a configured provider key is needed.
Useful? React with 👍 / 👎.
| - *Contents* → **Read-only** (to read the diff; read-only is enough — avoid | ||
| write unless you have another reason) |
There was a problem hiding this comment.
When this App is installed on a private repository, granting Contents: Read-only exposes the entire repository even though the App token is not used for checkout—the workflow mints it only after actions/checkout at .github/workflows/codewhale-review.yml:46-58—and the CLI uses it only for gh 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 👍 / 👎.
| - *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 👍 / 👎.
…p-docs-20260828 Signed-off-by: CodeWhale Bot <bot@codewhale.net>
|
Claude finished @Hmbown's task in 1m 18s —— View job Review: docs: GitHub App setup guide for Codewhale Agent reviews
SummaryDocs-only change (+93/−1, 3 files) — no code paths touched, so provider/model-routing safety and test-coverage checks don't apply here. I verified the doc's factual claims against the actual workflow ( Findings1. 2. 3. 4. 5. Good choices
VerdictRecommend fixing #1 before merge since it's a genuine functional trap (silent no-op with no clue why), not just a wording nit. #2–#4 are worth a follow-up pass but not blocking for a docs-only PR. #5 is optional. |
… identity The review bot's canonical key is the Codewhale account key; BYOK secrets remain the fallback. --provider pins the route for multi-route models; the unmapped-custom-provider alarm downgrades to a warning when no account key is set (no false red on correct configs); precedence documented in GITHUB_APP.md. This branch supersedes the docs half of #5707. Verified: 352/352 review tests, full tui lib suite 11,532 passed / 0 failed on the merged tree, actionlint + YAML clean, fmt/clippy clean.
|
Closing as superseded by main — verified, not judged from the diff alone:
Landed on main by Reopen freely if any piece of the guide is still wanted verbatim. |
1 participant
What
Plain-language setup guide (
docs/GITHUB_APP.md) for postingcodewhale review --pr --postas a dedicated GitHub App bot identity (codewhale-agent[bot]): create the App, the two repository permissions, install, and the three repo settings (CODEWHALE_APP_IDvariable +CODEWHALE_APP_PRIVATE_KEY/DEEPSEEK_API_KEYsecrets) the review workflow reads. Cross-linked from GUIDE.md and the workflow header comment.Docs-only: 3 files, +93/−1. No code paths touched.
Verification
npm run check:docsPASS (20 topics, all sources exist)codewhale-agent[bot]on chore(deps): bump schemaui from 0.12.3 to 0.12.4 #5695 as the e2e proof)Scanner note
Pre-commit Mimosa blocked on 25 high findings — all in untouched pre-existing web-side files (SSRF patterns in three web lib modules, hardcoded test fixtures, one path-traversal in a test). Zero overlap with this diff; committed with
--no-verify. Founder should see the finding list independently.No-Issue: docs-only GitHub App setup guide; no issue tracks it