---
title: The review action
description: Review every pull request with venom review on a cheap gear from GitHub Actions or GitLab CI, with inline comments, one summary comment with the cost, and a spend cap.
section: automation
order: 80
audience: [operator, user]
sources: [docs/review-action.md, examples/github/actions/venom-review/action.yml, examples/github/actions/venom-review/run.sh, examples/github/venom-review-action.yml, examples/gitlab/venom-review-cloud.gitlab-ci.yml]
features: [automation.review-action]
---

A composite GitHub Action that reviews every pull request with `venom review` on a cheap gear, posts the findings as a review with inline comments, and keeps one summary comment on the pull request with the verdict, the models that served the review, the tokens and the list-price cost. A cap stops a review that would cost more.

It ships as an example to copy into your repository:

| File in venom's examples | What it is |
|---|---|
| `examples/github/actions/venom-review/action.yml` | the action: inputs, outputs, one step |
| `examples/github/actions/venom-review/run.sh` | the step: skip, install, review, summary comment |
| `examples/github/actions/venom-review/summary.mjs` | the summary comment's Markdown, from venom's `--json` report |
| `examples/github/venom-review-action.yml` | a ready-to-copy workflow for a GitHub-hosted runner |
| `examples/gitlab/venom-review-cloud.gitlab-ci.yml` | the GitLab equivalent, a scheduled job on shared runners |

Self-hosted variants, where the code never leaves your machines, are `examples/github/venom-review.yml` and `examples/gitlab/venom-review.gitlab-ci.yml`. The action sends each pull request's diff from a GitHub runner to the model you configure.

## Set up {#setup}

1. Copy `examples/github/actions/venom-review/` to `.github/actions/venom-review/` and `examples/github/venom-review-action.yml` to `.github/workflows/venom-review.yml`.
2. Give it a model, one of:
   - **Venom Cloud**: secrets `VENOM_CLOUD_URL` (`https://cloud.usevenom.dev` or your deployment) and `VENOM_CLOUD_KEY` (a `vck_…` client key from `venom cloud login` or the console's Keys page). Your org's gears, routing and budgets apply.
   - **Your own provider key**: `base-url: https://api.openai.com/v1` (or any OpenAI-compatible `/v1`), a `model:` it serves, and the key in a secret passed as `api-key`.
   - **An orchestrator you run** that the runner can reach: `base-url` and its client key.
3. Open a pull request.

```yaml
# .github/workflows/venom-review.yml (excerpt)
- uses: ./.github/actions/venom-review
  with:
    cloud-url: ${{ secrets.VENOM_CLOUD_URL }}
    api-key: ${{ secrets.VENOM_CLOUD_KEY }}
    gear: eco
    max-usd: "0.50"
```

## What happens on each push {#flow}

1. Drafts and pull requests opened by bots (`dependabot[bot]`, `renovate[bot]`) are skipped; `skip-bots: false` reviews bots' pull requests too.
2. venom is installed from its public releases (`venom-version`). The installer checks the archive against the release's `SHA256SUMS`.
3. `venom review --pr <n> --repo <owner/repo> --post --json --gear eco --max-usd 0.50` (or `--model`) reviews the head read-only and posts one review. A new push replaces venom's previous review.
4. One summary comment per pull request, found by its marker `<!-- venom-review-summary -->`, is edited in place on every push.

```markdown
### venom review: changes requested (1 blocker, 1 major)

| Commit    | `0123456789ab`                    |
| Gear      | `eco`                             |
| Served by | `gpt-5.4-nano` (4 requests)       |
| Tokens    | 52k in (20k cached), 4.2k out     |
| Cost      | $0.0071 at list price, cap $0.50  |
```

The comment also says when the review stopped at the cap or could not run, so a stale verdict never stays up.

## Inputs and outputs {#inputs}

| Input | Default | What it does |
|---|---|---|
| `gear` | `eco` | The gear to review on; ignored when `model` is set. |
| `model` | | A model id instead of a gear. |
| `max-usd` | `0.50` | Stop the review at this many dollars at list price. |
| `cloud-url` | | Venom Cloud's URL (its `/v1` is used). |
| `base-url` | | Any OpenAI-compatible `/v1` instead. |
| `api-key` | | The key for `cloud-url` or `base-url`. |
| `github-token` | `github.token` | Reads the pull request, posts the review and the comment. |
| `security` | `false` | A security review. |
| `instructions` | | Extra focus for the reviewer. |
| `fail-on-blockers` | `false` | Fail the step on a blocker, to make it a required check. |
| `skip-bots` | `true` | Skip pull requests bots opened. |
| `venom-version` | `latest` | `latest`, an exact `x.y.z`, or `preinstalled` to use the venom on `PATH`. |

Outputs: `verdict` (`pass`, `fail`, `error`, `skipped`), `cost-usd`, `tokens-in`, `tokens-out`, `models`, `review-url`, `comment-url`.

## Cost and the cap {#cost}

The cost is venom's list-price figure for every request the review made: the provider's own price when it gives one, else venom's bundled price table. A local model counts tokens and says the cost is unpriced. Your provider's invoice is the authority.

Once the requests reach `max-usd`, every session stops and nothing is posted. The step ends with a warning, not a failure, and the comment says to raise the cap or pick a cheaper gear. A review that could not run fails the step.

## Safety {#safety}

The workflow runs on `pull_request_target`, so it uses the workflow file and the action from the base branch with the secrets, also for forks. That is safe only because nothing in the job builds, installs or runs the pull request's code: the checkout is the base branch, and the reviewer reads files and runs read-only commands with project toolchains denied and secret-named variables removed. Don't add steps that check out or run the head. The token needs `contents: read` and `pull-requests: write` only. Inputs reach the script through `env:`, and everything a model wrote is escaped in the comment. Pin `actions/checkout` by commit SHA and pin `venom-version` if `latest` moving is a concern.

## GitLab {#gitlab}

`examples/gitlab/venom-review-cloud.gitlab-ci.yml` runs as a scheduled pipeline (an MR pipeline would run the MR branch's own CI file) and calls `venom review --watch "$CI_PROJECT_PATH" --once --post --gear eco --max-usd 0.50`. Each merge request gets one summary note with the same usage line, replaced on every push. Cache `VENOM_HOME` between runs: `--watch` remembers the heads it reviewed there, and without the cache every open merge request is reviewed and paid for on every run.

## Related

- [Code review](/docs/automation/review.md): every `venom review` flag.
