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

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.

AgentModelCredential (an Actions secret)
Claude CodeClaude OpusCLAUDE_CODE_OAUTH_TOKEN, from claude setup-token with a Claude Pro or Max plan. Or ANTHROPIC_API_KEY, an Anthropic API key.
CodexGPT-6.1-SolOPENAI_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

A ChatGPT Plus or Pro plan cannot run reviews yet. Use an OpenAI API key instead.
  • 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/flow from the Plus registry with it. Create one in Tokens.

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 Flow pull request reviews in this project. If a step fails, work out what is wrong and fix it.

1. Check that the project has a GitHub remote, and read the owner and repository from it. Find the folder of the AdonisJS app: the folder that has flow.lock and .flow/review.yml. It is the root of the repository, or a folder inside it when the repository is a monorepo. If no folder has them, stop and tell me to install Flow first: https://plus.adonisjs.com/docs/get-started/installation
   If more than one folder has them, ask me which app to set up.
   Then check whether `gh auth status` prints my account. Use the GitHub CLI in the steps below only when it does.

2. Find the package manager from the lockfile.

3. Ask me: "Which agent should review your pull requests: Claude Code or Codex?" Then ask which credential I have:
   - Claude Code: CLAUDE_CODE_OAUTH_TOKEN (a Claude Pro or Max plan, made with `claude setup-token`) or ANTHROPIC_API_KEY (an Anthropic API key).
   - Codex: OPENAI_API_KEY (an OpenAI API key) or CODEX_ACCESS_TOKEN (a ChatGPT Business or Enterprise access token).

4. Write .github/workflows/flow-review.yml with this content. Use the install command of the package manager (npm ci, pnpm install --frozen-lockfile, yarn install --immutable or bun install --frozen-lockfile). With Yarn, which does not read .npmrc, add a step before the install that runs `yarn config set --home npmScopes.adonisplus.npmAuthToken "$ADONISJS_PLUS_TOKEN"` with `ADONISJS_PLUS_TOKEN: ${{ secrets.ADONISJS_PLUS_TOKEN }}` in its env, in place of NODE_AUTH_TOKEN. In the last step, keep only the line of the credential I picked.
   With pnpm, the runner has no pnpm. Add `- uses: pnpm/action-setup@v4` before actions/setup-node. When package.json has no `packageManager` field, give it `with: version: <the major version of pnpm>`.
   With Bun, the runner has no Bun. Add `- uses: oven-sh/setup-bun@v2` before actions/setup-node. Bun reads the token from the .npmrc that actions/setup-node writes.
   When the app is in a folder inside the repository, add `working-directory: <path of the app>` to the `flow install --ci` step, and add the same line under `with:` of the last step. Use the real path of the app from the root of the repository. Do not write a path that you did not find.

   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 }}
             ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
             OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
             CODEX_ACCESS_TOKEN: ${{ secrets.CODEX_ACCESS_TOKEN }}

5. Set `agent: claude` or `agent: codex` in the .flow/review.yml of the app, for the agent I picked.

6. Tell me to add two secrets to the repository myself, and wait until I say I did. Never ask me for a secret, and never print one.
   - ADONISJS_PLUS_TOKEN: a token I create at https://plus.adonisjs.com/account/tokens
   - The credential I picked.
   With the GitHub CLI, tell me to run `gh secret set ADONISJS_PLUS_TOKEN` and `gh secret set <the credential>` in my terminal.
   Without it, give me this link with the owner and repository filled in: https://github.com/<owner>/<repo>/settings/secrets/actions/new
   Tell me to open it once for each secret, type the name in "Name", paste the value in "Secret", and select "Add secret".

7. Create the branch flow-review-setup, commit the two files with the message "Set up Flow reviews", and push it with git.
   With the GitHub CLI, open the pull request with `gh pr create --title "Set up Flow reviews"` and show me its link.
   Without it, give me this link with the owner, the repository and the default branch filled in: https://github.com/<owner>/<repo>/compare/<default branch>...flow-review-setup?expand=1
   Tell me to check that the title is "Set up Flow reviews" and select "Create pull request".

8. Last, tell me to open my dashboard at https://plus.adonisjs.com/account. The repository shows "Merge the setup pull request to turn on reviews.", with "Review and merge". Tell me to merge the pull request from there. Then the repository shows "Waiting for the first pull request", and Flow reviews the next pull request.

If a step fails:
- A push of the workflow file refused for the `workflow` scope means the GitHub CLI token signs your git pushes and lacks the scope. Tell me to run `gh auth refresh -s workflow`.
- Adding a secret refused, or no "New repository secret" page, means I am not an admin of the repository. Tell me to ask one.
  1. Create .github/workflows/flow-review.yml. The Flow App starts this workflow for each pull request, so it runs only on the workflow_dispatch event.

    .github/workflows/flow-review.yml
    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@v4 before actions/setup-node, because the runner has no pnpm. Give it with: version: 11, or your major version of pnpm, unless package.json has a packageManager field. With Bun, add - uses: oven-sh/setup-bun@v2 before actions/setup-node, for the same reason. With Yarn, Yarn does not read .npmrc. Replace the env of the install step with a step before it, run: yarn config set --home npmScopes.adonisplus.npmAuthToken "$ADONISJS_PLUS_TOKEN", with env: 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. Add working-directory to the flow install step and to the Flow review Action, with the path of your app from the root of the repository. The example uses apps/backend. Use the path of your own app.

    .github/workflows/flow-review.yml
          - 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/backend
  2. Set the agent in .flow/review.yml. Flow reads it from your default branch, so a pull request cannot switch it.

    .flow/review.yml
    agent: claude # or codex
  3. Open your repository on GitHub, then Settings → Secrets and variables → Actions → New repository secret. Add two secrets:

    With the GitHub CLI, run gh secret set ADONISJS_PLUS_TOKEN and gh secret set <name> instead.

  4. Commit both files on a new branch, push it, and open a pull request. Your dashboard shows the repository as "Setup pull request open".

  5. Once you merge it, the dashboard shows "Waiting for the first pull request". Flow reviews every pull request after that.

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.

Lenses

What each lens checks, and which files it reads.

Configuration

The settings of .flow/review.yml.