GitHub Action

Octopus GitHub Action

AI-powered, context-aware code review for every pull request. Free for open source. Add an API key to unlock your team's knowledge base, custom rules, and full review history.

One workflow file. Reviews on every PR.

Drop the YAML below into .github/workflows/octopus.yml, commit it, and your next pull request gets an inline review from Octopus with severity-rated findings.

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

# .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.

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

.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
        with:
          octopus-api-key: ${{ secrets.OCTOPUS_API_KEY }}

Community vs API Key

Feature	Community	With API Key
AI code review	Yes	Yes
Codebase indexing	Yes	Yes
Daily limit	5 per repo / day	Unlimited (plan-based)
Private repos	Not supported	Supported
Knowledge base	Not included	Custom docs & rules
Custom config	Not included	Severity, categories, paths
Review history	Not included	Full history & analytics
Feedback learning	Not included	Team-wide suppression

What an API Key Unlocks

Knowledge Base

Upload internal docs, style guides, and architecture notes. Reviews cite them directly.

Custom Rules

Configure severity thresholds, disable categories, and tune the reviewer to match your team.

Full Review History

Browse past reviews, track findings over time, and analyze trends across PRs.

Feedback Learning

Thumbs-down a finding once and the reviewer suppresses it team-wide.

Get your API key

Inputs

Input	Required	Default
`octopus-api-key`	No	`(none)`
Octopus API key (oct_*). Required for private repos. Optional for public repos (free community tier).
`github-token`	No	`${{ github.token }}`
GitHub token used to fetch the diff and post review comments. The default token is auto-provided by Actions.
`api-url`	No	`https://octopus-review.ai`
Base URL of the Octopus API. Override this if you self-host.
`force-reindex`	No	`false`
Force re-index the repository before reviewing, even if a recent index exists.
`reindex-threshold-hours`	No	`24`
Re-index if the last index is older than this many hours.

Outputs

Output	Description
`findings-count`	Total number of findings in the review.
`summary`	Review summary text.

Permissions

The action needs these GitHub token permissions:

contents: read

Fetch the PR diff and index the repository.

pull-requests: write

Post review comments and summary.

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.

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

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

FAQ

Does Octopus store my code?

No. Source code is used temporarily for indexing (creating vector embeddings) and reviewing. Source code is never stored. Embeddings are cached to speed up subsequent reviews.

How does the community tier work?

Public repositories can use Octopus with no signup. A community organization is created automatically per GitHub owner (user or org). The default daily limit is 5 reviews per repository.

What models does Octopus use?

Claude (Anthropic) for code review and OpenAI for embeddings by default. Organizations with API keys can configure custom models.

Can I configure what gets reviewed?

With an API key you can customize severity thresholds, disable specific finding categories, and add knowledge documents that guide the reviewer. See the .octopusignore reference to exclude files from review and indexing.