Docs › CLI › Reviewing a branch
Reviewing a branch
Review a branch's changes from the terminal or in a pull request, and get only findings that describe a concrete failure.
On this page
- What it compares against
- Options
- Output
- Exit codes
- Review every pull request
- From the editor and the conversation
- If something goes wrong
astracode-agent review reads what this branch changed and reports only problems it can show will break: each finding names the input or state and the wrong result that follows. Naming, style and refactoring suggestions are left out. It reports at most eight findings, most serious first, and a review that finds nothing says so. It is read-only: every edit and command is refused.
Terminal
astracode-agent review # against the branch's base
astracode-agent review --base origin/main # against a ref you name
astracode-agent review --output-format json # for a script
What it compares against
The review covers the changes since the merge base of HEAD and the base, so work others landed on the base meanwhile is not included. Without --base, it takes the first of these that exists:
- The branch's upstream (
@{upstream}). - The remote's default branch (
origin/HEAD). origin/main, thenorigin/master.main, thenmaster.
The diff it reads is cut at 120,000 characters; the result says when it was. The agent reads the code around each change, not only the diff.
Options
| Option | Default | What it does |
|---|---|---|
--base <ref> | as above | What to compare against. An empty ref, or one starting with -, is refused. |
--output-format text|json | text | A readable list, or one JSON object. |
--max-steps <n> | 60 | The step limit for the review. |
--cwd <dir> | the current folder | Any folder inside the repository; the review runs from its root. |
--trust | off | Load the project's rules, skills and agents. Without it the folder is untrusted, because a fork's pull request reaches the review. |
-v, --verbose | off | The agent's log and each tool it calls, on stderr. |
Output
Text: Reviewed N file(s) against the base, then No findings. or the count and each finding as its severity, file:line, a summary, and the failure on the next line. JSON:
--output-format json
{
"type": "result",
"ok": true,
"end": "finished",
"base": "origin/main",
"files": ["src/billing.py"],
"findings": [{
"file": "src/billing.py", "line": 42,
"summary": "Refunds are added to the total",
"failure": "A refund of 10 on an invoice of 100 totals 110 instead of 90.",
"severity": "high", "category": "logic"
}],
"reported": true,
"truncated": false,
"summary": "...",
"steps": 23
}
severity is high, medium or low; category may be absent. reported is false when the review ended without reporting its findings, and truncated is true when the diff was cut. On failure, error says why.
Exit codes
| Code | Meaning |
|---|---|
| 0 | The review finished, with or without findings. A branch with nothing to review also exits 0. |
| 1 | It did not finish, ended without reporting its findings, or the gateway refused. |
| 2 | Not inside a git repository; no common ancestor with the base (In CI, check out with fetch-depth: 0.); could not work out what to compare against; pass --base <ref>; a usage error; or not signed in. |
| 130 | Interrupted. |
Review every pull request
The AstraCode Review GitHub Action runs this review on each pull request and comments on what it finds.
- Create an API key on your dashboard under API & SSH keys.
- In the repository, add it as a secret named
ASTRACODE_API_KEY(Settings, Secrets and variables, Actions). - Add the workflow below as
.github/workflows/astracode-review.yml.
.github/workflows/astracode-review.yml
name: AstraCode review
on:
pull_request:
permissions:
contents: read
pull-requests: write
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0
- uses: AstraCode-io/review-action@v1
with:
api-key: ${{ secrets.ASTRACODE_API_KEY }}
| Input | Default | What it does |
|---|---|---|
api-key | required | Your AstraCode API key. |
fail-on | none | Fail the check on a finding at or above low, medium or high. |
max-steps | 60 | The step limit for the review. |
version | the latest | The astracode-agent version to install. |
github-token | github.token | The token used to comment. Needs pull-requests: write. |
- Each finding is an inline comment on its line, posted once: the next push does not repeat it.
- One summary comment lists every finding, including those on lines outside the diff, and is edited on each push rather than posted again.
- The
findingsoutput is the number of findings. - Each review is billed to the account that owns the key, within any limit on the key.
- Pull requests from forks do not get repository secrets on
pull_requestevents, so they are skipped unless the workflow provides the key another way.
From the editor and the conversation
In a conversation, /review (or /review <branch>) runs the same review. In the editor, Review This Branch does it from the Source Control view; see Git.
If something goes wrong
- cannot find a common ancestor of HEAD and the base: the checkout is shallow. Use
fetch-depth: 0. - could not work out what to compare against: the branch tracks nothing and there is no
mainormaster. Pass--base. - the review ended without reporting its findings (exit 1): it ran out of steps. Raise
--max-steps. - Everything else: CLI problems.
← Scripts and CI Zed and JetBrains →
All documentation
Get started
Using the editor
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems