Alokai

AI code review

Alokai ships an AI code reviewer that runs in your own GitHub Actions and posts findings as inline review comments on your pull requests. The review is powered by the @alokai/cli-plugin-review plugin for the Alokai CLI and an LLM endpoint provisioned by Alokai.

Everything runs on your infrastructure and under your identity: the workflow executes in your repository's Actions, and comments are posted by a GitHub App that you own. Alokai does not host a shared bot.

What you need

  1. Your own GitHub App, registered under your organization, so the bot posts comments under an identity you own.
  2. An LLM endpoint, model and API key. These are provisioned by Alokai - contact your Alokai representative to receive the base URL, model name and key for your project. Do not commit the key into the repository.

1. Install the review plugin

Add the plugin as a dev dependency:

yarn add -D @alokai/cli-plugin-review

2. Add the workflow

Create .github/workflows/ai-review.yml with the following content:

.github/workflows/ai-review.yml
name: "AI Review"

# Alokai AI code review. Disabled by default: set the repo variable
# AI_REVIEW_ENABLED to 'true' after completing the setup.
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

concurrency:
  group: "ai-review-${{ github.event.pull_request.number }}"
  cancel-in-progress: true

# Branches that should not be reviewed (automated/bot PRs).
# SKIP_BRANCHES: comma-separated head-branch prefixes, e.g. "dependabot/,renovate/".
env:
  SKIP_BRANCHES: "dependabot/"

defaults:
  run:
    shell: "bash"

jobs:
  review:
    name: "AI Review"
    runs-on: "ubuntu-latest"
    if: >-
      ${{
        vars.AI_REVIEW_ENABLED == 'true'
        && github.event.pull_request.draft == false
        && !contains(github.event.pull_request.labels.*.name, 'skip-ai-review')
      }}
    timeout-minutes: 30
    permissions:
      contents: "read"
      id-token: "write"
      issues: "write"
      pull-requests: "write"
    steps:
      - name: "Mint identity token"
        id: "mint_identity_token"
        if: |-
          ${{ vars.AI_REVIEW_APP_ID }}
        uses: "actions/create-github-app-token@v2"
        with:
          app-id: "${{ vars.AI_REVIEW_APP_ID }}"
          private-key: "${{ secrets.AI_REVIEW_APP_PRIVATE_KEY }}"
          permission-contents: "read"
          permission-issues: "write"
          permission-pull-requests: "write"

      - name: "Checkout repository"
        uses: "actions/checkout@v5"
        with:
          fetch-depth: 0

      - name: "Check if review should run"
        id: "gate"
        env:
          HEAD_REF: "${{ github.head_ref }}"
        run: |
          HEAD="${HEAD_REF}"

          IFS=',' read -ra PATTERNS <<< "${SKIP_BRANCHES}"
          for pattern in "${PATTERNS[@]}"; do
            [[ -z "${pattern}" ]] && continue
            if [[ "${HEAD}" == ${pattern}* ]]; then
              echo "⏭ Skipping review: branch '${HEAD}' matches skip pattern '${pattern}'"
              echo "skip=true" >> "${GITHUB_OUTPUT}"
              exit 0
            fi
          done

          echo "✓ Branch '${HEAD}' is eligible for review"
          echo "skip=false" >> "${GITHUB_OUTPUT}"

      - name: "Install dependencies"
        if: ${{ steps.gate.outputs.skip != 'true' }}
        uses: "./.github/actions/setup"
        with:
          npm_user: "${{ vars.NPM_USER }}"
          npm_password: "${{ secrets.NPM_PASS }}"
          npm_email: "${{ vars.NPM_EMAIL }}"
          npm_registry_url: "${{ vars.NPM_REGISTRY_URL }}"

      - name: "Install review plugin into Alokai CLI"
        if: ${{ steps.gate.outputs.skip != 'true' }}
        run: yarn alokai plugins link node_modules/@alokai/cli-plugin-review

      - name: "🚀 Run AI review"
        if: ${{ steps.gate.outputs.skip != 'true' }}
        env:
          GITHUB_TOKEN: "${{ steps.mint_identity_token.outputs.token || secrets.GITHUB_TOKEN || github.token }}"
          GITHUB_REPOSITORY: "${{ github.repository }}"
          PR_NUMBER: "${{ github.event.pull_request.number }}"
          AI_REVIEW_API_KEY: "${{ secrets.AI_REVIEW_API_KEY }}"
          AI_REVIEW_BASE_URL: "${{ vars.AI_REVIEW_BASE_URL }}"
          AI_REVIEW_MODEL: "${{ vars.AI_REVIEW_MODEL }}"
          # Set repo variable AI_REVIEW_INCREMENTAL to 'true' to review only the
          # changes since the last bot review on each re-run.
          AI_REVIEW_INCREMENTAL: "${{ vars.AI_REVIEW_INCREMENTAL }}"
        run: |
          # Flags are added only when their variable is set, so unset vars fall
          # back to the plugin defaults instead of overriding them with "".
          ARGS=()
          if [[ -n "${AI_REVIEW_BASE_URL}" ]]; then ARGS+=(--base-url "${AI_REVIEW_BASE_URL}"); fi
          if [[ -n "${AI_REVIEW_MODEL}" ]]; then ARGS+=(--model "${AI_REVIEW_MODEL}"); fi
          if [[ "${AI_REVIEW_INCREMENTAL}" == "true" ]]; then ARGS+=(--incremental); fi
          yarn alokai ai review "${ARGS[@]}"

The workflow is disabled by default - it no-ops until you set the AI_REVIEW_ENABLED repository variable to true in the last step.

The "Install dependencies" step uses the ./.github/actions/setup composite action that ships with generated Alokai storefronts (npm registry auth + yarn install). If your repository doesn't have it, replace that step with your own Node setup and yarn install.

3. Register your GitHub App

Register a GitHub App under your own organization (you own it; it is not shared with Alokai or other customers).

A manifest pre-fills the name and permissions, and returns the App ID and private key in one step - no manual configuration. This is the manifest the app needs:

manifest
{
  "name": "AI Review",
  "url": "https://alokai.com",
  "public": false,
  "default_permissions": {
    "contents": "read",
    "issues": "write",
    "pull_requests": "write"
  },
  "redirect_url": "https://alokai.com"
}

GitHub only accepts a manifest as a form POST, so save this snippet as register-app.html, replace YOUR_ORG, open the file in a browser and submit:

register-app.html
<form action="https://github.com/organizations/YOUR_ORG/settings/apps/new" method="post">
  <input type="hidden" name="manifest" value='{"name":"AI Review","url":"https://alokai.com","public":false,"default_permissions":{"contents":"read","issues":"write","pull_requests":"write"},"redirect_url":"https://alokai.com"}'>
  <button>Register the AI Review GitHub App</button>
</form>

After you confirm the registration, GitHub redirects to the redirect_url with a temporary code query parameter. Exchange it within one hour for the app's credentials:

gh api -X POST /app-manifests/<code>/conversions

The response contains the id (your App ID) and pem (the private key) - save both for the next step.

Manually

Alternatively, register the app by hand with these repository permissions:

  • Contents: Read-only - read the code to review.
  • Issues: Read & write - post and update review comments.
  • Pull requests: Read & write - post inline review comments and replies.

Generate a private key for the App and note its App ID.

Install it

Either way, finish by installing the App on the repositories that should get AI review (Settings → GitHub Apps → Install).

4. Configure repository variables and secrets

In Settings → Secrets and variables → Actions, add:

Variables

NameValue
AI_REVIEW_ENABLEDtrue to turn the workflow on (see Opt-out).
AI_REVIEW_APP_IDYour GitHub App's ID.
AI_REVIEW_BASE_URLThe OpenAI-compatible LLM endpoint provided by Alokai.
AI_REVIEW_MODELThe model name provided by Alokai.
AI_REVIEW_INCREMENTAL(optional) true to review only changes since the last bot review on re-runs.

Secrets

NameValue
AI_REVIEW_APP_PRIVATE_KEYYour GitHub App's private key (.pem contents).
AI_REVIEW_API_KEYThe LLM API key provided by Alokai.

5. Enable it

Set the AI_REVIEW_ENABLED variable to true. The next pull request (or an existing one that is updated) will get an AI review.

Usage

  • Automatic review: runs on every non-draft PR.
  • Skip a single PR: add the skip-ai-review label to that PR.

Opt-out

  • Disable: leave AI_REVIEW_ENABLED unset, or set it to any value other than true. The workflow no-ops.
  • Remove entirely: delete .github/workflows/ai-review.yml.
  • Skip one PR: use the skip-ai-review label.

Previous

Syncing skills

Next

Troubleshooting

On this page

What you need1. Install the review plugin2. Add the workflow3. Register your GitHub AppFrom a manifest (recommended)ManuallyInstall it4. Configure repository variables and secretsVariablesSecrets5. Enable itUsageOpt-out