Skip to content
Docs menu

The review action

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.

View .md

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

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

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

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

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

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

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.