GitHub setup
On this page
This guide turns on Flow code reviews for the pull requests of a GitHub repository. You will:
- Connect GitHub on your dashboard
- Set up the repository, with one prompt to your coding agent or by hand
- Merge the setup pull request, and get a review on the next one
Supported agents
Section titled "Supported agents"Flow reviews run on Claude Code or Codex, in your own GitHub Actions. The agent uses your credential, and you pay its vendor for the tokens. Flow never receives the credential.
| Agent | Model | Credential (an Actions secret) |
|---|---|---|
| Claude Code | Claude Opus | CLAUDE_CODE_OAUTH_TOKEN, from claude setup-token with a Claude Pro or Max plan. Or ANTHROPIC_API_KEY, an Anthropic API key. |
| Codex | GPT-6.1-Sol | OPENAI_API_KEY, an OpenAI API key. Or CODEX_ACCESS_TOKEN, an access token of a ChatGPT Business or Enterprise workspace. |
The credential you add picks the agent. With credentials for both, set agent: claude or agent: codex in .flow/review.yml.
Note
Before you start
Section titled "Before you start"- Flow installed in the project. Read Installation and setup.
- The Flow GitHub App on the account or organization that owns the repository. On your dashboard, select "Install the GitHub App". If you installed it from GitHub, select "Connect GitHub" instead.
- The GitHub CLI, signed in, if you have it. With it, the setup adds the secrets and opens the pull request for you. Without it, the setup gives you the GitHub pages to open.
- A credential from Supported agents.
- A Plus registry token for CI. The workflow installs
@adonisplus/flowfrom the Plus registry with it. Create one in Tokens.
Let your agent set it up
Section titled "Let your agent set it up"Paste this prompt into your coding agent, in the root of your project. It writes the workflow, has you add the secrets, and opens the setup pull request.
Set up by hand
Section titled "Set up by hand"Add the workflow
Section titled "Add the workflow"Create
.github/workflows/flow-review.yml. The Flow App starts this workflow for each pull request, so it runs only on theworkflow_dispatchevent.name: Flow review on: workflow_dispatch: inputs: payload: description: Sent by the Flow App. Do not edit. required: true permissions: contents: read id-token: write jobs: review: runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 24 registry-url: https://plus.adonisjs.com/registry/ scope: '@adonisplus' - run: npm ci env: NODE_AUTH_TOKEN: ${{ secrets.ADONISJS_PLUS_TOKEN }} - run: npx @adonisplus/flow install --ci - uses: adonisjs-plus/flow-review-action@v0.6.0 with: payload: ${{ inputs.payload }} env: CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}Use your package manager's install command in place of
npm ci. With pnpm, add- uses: pnpm/action-setup@v4beforeactions/setup-node, because the runner has no pnpm. Give itwith: version: 11, or your major version of pnpm, unlesspackage.jsonhas apackageManagerfield. With Bun, add- uses: oven-sh/setup-bun@v2beforeactions/setup-node, for the same reason. With Yarn, Yarn does not read.npmrc. Replace theenvof the install step with a step before it,run: yarn config set --home npmScopes.adonisplus.npmAuthToken "$ADONISJS_PLUS_TOKEN", withenv: ADONISJS_PLUS_TOKEN: ${{ secrets.ADONISJS_PLUS_TOKEN }}. In the last step, list the credential you use from Supported agents.Flow reviews one AdonisJS app in each repository: the app that has
.flow/review.yml. In a monorepo, the review runs inside that app. Addworking-directoryto theflow installstep and to the Flow review Action, with the path of your app from the root of the repository. The example usesapps/backend. Use the path of your own app.- run: npx @adonisplus/flow install --ci working-directory: apps/backend - uses: adonisjs-plus/flow-review-action@v0.6.0 with: payload: ${{ inputs.payload }} working-directory: apps/backendChoose the agent
Section titled "Choose the agent"Set the agent in
.flow/review.yml. Flow reads it from your default branch, so a pull request cannot switch it.agent: claude # or codexAdd the secrets
Section titled "Add the secrets"Open your repository on GitHub, then Settings → Secrets and variables → Actions → New repository secret. Add two secrets:
ADONISJS_PLUS_TOKEN, a token from Tokens.- Your credential, under its name from Supported agents.
With the GitHub CLI, run
gh secret set ADONISJS_PLUS_TOKENandgh secret set <name>instead.Open the setup pull request
Section titled "Open the setup pull request"Commit both files on a new branch, push it, and open a pull request. Your dashboard shows the repository as "Setup pull request open".
Merge it
Section titled "Merge it"Once you merge it, the dashboard shows "Waiting for the first pull request". Flow reviews every pull request after that.
Check that it works
Section titled "Check that it works"Open a pull request in the repository. Within a minute, it gets a "Flow review" check that shows the review's progress. When the review ends, the findings appear as comments on the changed lines, and the check names the agent and the model that reviewed it.
On your dashboard, the repository shows "Reviewing" with the time of the last review. If it shows another state, its detail line says what to fix.
GitHub pull requests shows each state of the "Flow review" check, and the comments that start a review again. To review a branch on your computer before you open a pull request, see Local reviews.