Axon Shaft docs

How a review runs

What starts a review, which pull requests it skips, what happens on each push, and the order the checks run in.

What starts a review

The workflow runs on these pull request events, and the Code review's When it runs setting picks which of them start a review:

GitHub eventIn the dashboardDefault
opened, reopenedPull request openedOn
synchronizeEvery pushOn
ready_for_reviewReady for reviewOn

A /review comment from someone with write access also starts one, whatever these settings say.

Axon Shaft treats a draft like any other pull request. With Pull request opened on, a draft is reviewed when it's opened, and with Every push on, on each push. Marking it ready reviews it again when Ready for review is on.

The checks before a review

The action asks the Axon Shaft API for its run first. The API answers with the first of these that applies, and a run that stops ends with a notice that gives the reason:

  1. The app isn't installed on the repo, or the repo isn't a project: the run fails with not_installed or not_a_project.
  2. The project is paused.
  3. Code review is off, or the event isn't one of its When it runs choices.
  4. The pull request is from a fork, and the forks setting holds it back.
  5. One of the Code review's filters skips it. A skip label is checked first, then Axon Shaft's own pull requests, bots, outside contributors and the target branch. See Skipping a pull request.
  6. The project or account reached its monthly spending cap.
  7. Neither the project nor its account has a Claude token: the run fails with no_claude_token.

A /review skips the event check in step 3 and all of steps 4 and 5, and instead needs the commenter to have write access. It still stops when Code review is off.

A project can have several review automations, but only the first one that's on, in the order of the Automations tab, runs.

Outside contributors

An outside contributor is someone whose GitHub author_association on the pull request isn't owner, member or collaborator. GitHub leaves out access that comes through a team or a private org membership, so before skipping one, the API asks GitHub for the author's permission on the repo. An author with write or admin access is reviewed. The outside setting is Don't review them by default.

Forks

On pull_request_target, a fork's pull request gets a run like any other. The forks setting then decides:

SettingWhat happens
Review automatically (the default)It's reviewed like any other pull request.
Ask a maintainer firstaxonshaft[bot] comments once that someone with write access can start the review with /review, and the run ends with a notice. Later pushes don't repeat it.
Only when a maintainer comments /reviewNothing is posted, and the run ends with a notice.

A workflow still on pull_request gets no OIDC token for a fork's run, so every fork's pull request ends with fork_pull_request.

What the review reads

On pull_request_target and on a comment, the workflow's checkout holds the base branch. The action fetches the pull request's head commit with the run's GitHub token, passed on that one git fetch command and never saved, and checks it out detached. The fetch is as deep as the checkout: one commit by default, or the whole history with fetch-depth: 0.

The model then reads the change with Read, Grep, Glob, git diff, git log and git show, inside the checkout only. It never edits files, installs anything or runs the pull request's code. What runs in CI lists the limits.

Its prompt holds:

  • the pull request's title, author, body, commits and diff, with files that match the skip globs left out and files that match focus marked;
  • the comments of people inside the repo, and nobody else's;
  • the previous review's findings;
  • the repo guide files from the base branch, and the project's review rules;
  • the steps of each checklist that runs, and the merge gates.

A diff longer than 200,000 characters is cut, and the model reads the rest from the checkout.

On each push

  • A new push cancels a review of the same pull request that's still running, through the workflow's concurrency group.
  • The summary comment is edited, not posted again. While the new review runs, its card shows a reviewing image. GitHub sends no email when a comment is edited.
  • A finding that already has an inline comment isn't posted again.
  • When a push fixes a finding, its inline thread is resolved, and the summary counts it under the findings this push fixed.
  • The check runs are posted on the new head commit. The earlier commit keeps its own.

Removing a skip label, or changing a setting, doesn't start a review by itself. The next push, or a /review, does.

Last updated on