Octopus GitHub Action

Quick Start

For public repositories, no signup or API key is required. The action runs in community mode by default, with up to 5 reviews per repository per day.

# .github/workflows/octopus.yml
name: Octopus Review
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: octopusreview/action@v1

That's it. Open a pull request, and Octopus will index the repo on the first run, then post inline review comments with severity levels and suggested fixes.

Private Repos & Full Access

Private repositories require an Octopus API key. Adding a key also unlocks the full feature set on public repos: your team's knowledge base, custom rules, full review history, and unlimited reviews within your plan.

1. Sign up at octopus-review.ai
2. Go to Settings > API Keys and create a key (it starts with oct_)
3. Add it to your repository as a secret named OCTOPUS_API_KEY

name: Octopus Review
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: octopusreview/action@v1
        with:
          octopus-api-key: ${{ secrets.OCTOPUS_API_KEY }}

Community vs API Key

What an API Key Unlocks

Inputs

Outputs

Permissions

The action needs these GitHub token permissions:

For private repos, the default GITHUB_TOKEN already has access to the repository it runs in. The token is passed to Octopus for indexing only, is never stored, and expires when the workflow ends.

Fork Pull Requests

GitHub makes GITHUB_TOKEN read-only for pull requests opened from forks when using the pull_request event. This is a deliberate GitHub security measure against untrusted forks, and it means Octopus cannot post its review on those PRs. Reviews on branches within the same repository are unaffected.

To enable reviews on fork pull requests, switch the trigger to pull_request_target. The Octopus action only reads the PR diff through the GitHub API; it never checks out or runs the fork's code, so this is safe as long as your workflow does not add a checkout step that builds the fork head.

# .github/workflows/octopus.yml
name: Octopus Review
on:
  pull_request_target:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: octopusreview/action@v1

For larger repositories that prefer not to grant a writable token in CI at all, install the Octopus GitHub App instead. The App posts reviews with its own installation permissions, so fork token restrictions never apply and no workflow file is needed.

Examples

Restrict reviews to specific paths

on:
  pull_request:
    types: [opened, synchronize]
    paths:
      - "src/**"
      - "lib/**"

Use outputs in subsequent steps

steps:
  - uses: octopusreview/action@v1
    id: review
    with:
      octopus-api-key: ${{ secrets.OCTOPUS_API_KEY }}

  - if: steps.review.outputs.findings-count != '0'
    run: echo "Octopus found ${{ steps.review.outputs.findings-count }} issues"

How It Works

1. A pull request is opened or updated.
2. The action fetches the PR diff (capped at 500KB).
3. Octopus indexes your repo on the first run, then caches the index for the configured threshold.
4. The diff is reviewed with full codebase context, not just the changed lines.
5. Findings are posted as inline PR review comments with severity levels and suggested fixes.

FAQ

Related