Axon Shaft docs

Quick start

Install the app, add the repo, save a Claude token, add the workflow, and open a pull request to see the first review.

You need admin rights on the GitHub account, or the Admin or Maintain role on the repo, and a Claude plan or a Claude Console API key.

Install the GitHub app

Install the AxonShaft app on the account, for all repos or only the ones you pick. Its comments come from axonshaft[bot].

Add the repo as a project

Sign in on shaft.axonpack.dev with GitHub, open the account, and add the repo. The setup walkthrough opens and takes you through the workflow, the Claude token, the model and the automations. Make sure Code review is on in its Automations step.

Save a Claude token

In the walkthrough, or on the project's Claude token page, save one of these:

  • with a Claude Pro or Max plan, the token that claude setup-token prints;
  • with Claude Console billing, an API key.

A token saved on the account covers every project that has none of its own. Claude tokens has the details.

Add the workflow

The walkthrough's Add the workflow card commits .github/workflows/shaft.yml to the default branch, or opens a pull request with it when the branch is protected. You can also copy the file from the card and commit it yourself. The workflow file explains each line.

Open a test pull request

Push a branch with a small change and open a pull request into the default branch. To see the output in the job log before anything is posted, add with: { dry_run: true } under uses: axonpack/shaft-actions@v1 first.

Check the first review

When the run finishes, the pull request shows:

  • an Axon Shaft / review check run, in progress while the review runs, then passing with a link to the summary;
  • the summary comment from axonshaft[bot], with a card colored by the verdict, the findings table and a chip for each check;
  • inline comments on the lines with blocking or should-fix findings;
  • one check run per checklist, such as Axon Shaft / correctness.

The run also appears on the project's Runs page on the dashboard, with its own page.

If nothing shows up

Open the pull request's Checks tab, or the repo's Actions tab, and find the Axon Shaft job.

  • If there's no Axon Shaft job at all, the workflow file isn't on the pull request's base branch yet. On pull_request_target, GitHub runs the workflow file from the base branch, so a workflow added only in the test pull request doesn't run.
  • If the job failed, the step's message says what to do, and the job summary shows a card with the code. Look the code up in Failure and notice codes. The common ones on a first run are not_installed, not_a_project, no_claude_token and missing_id_token.
  • If the job passed and posted nothing, the run ended with a notice, which the job's annotations show. Either Code review is off, the event isn't one of its "When it runs" choices, the pull request is from a bot, an outside contributor or a fork the project holds back, it has a skip label, or the project is paused. Runs that end with a notice lists each one.
  • With dry_run: true, the review is in the job log only. Remove the input to post it.
  • If the review posted but no check runs did, the installation hasn't approved the app's Checks (write) permission. The job log warns about it, and the account's admin can approve it in the app's settings on GitHub.

Last updated on