Arcanist code review: customer guide

Arcanist reviews your pull requests on GitHub. It works inside a private copy of your repository. It reads the change and the code around it. It can run commands to check a possible problem before it posts a review on GitHub.

Fastest path to your first review

  1. Select Continue with GitHub. Arcanist opens your workspace and asks you to connect repositories.
  2. Choose repositories in the GitHub App, then return to Arcanist and select Check again.
  3. Prepare the repository. Wait until its status is Ready.
  4. Open Reviews, select Review this PR, and start the review. You can also comment @tryarcanist /review on a pull request.

What you need

What Arcanist does

Arcanist copies the latest code from the pull request into a private workspace. It can install what the project needs and run tests or other project commands. It posts a merge recommendation, a short summary, findings tied to lines of code, the checks it ran, and the exact commit it reviewed.

Arcanist reports findings. It does not approve the pull request, request changes, merge code, or deploy your application.

See a real result

A published review shows a merge recommendation, each finding with its problem and fix, the reviewed commit, and the command to run another review. Run your first review on a small pull request to see one on your own repository.

Security basics

Treat repository credentials and CLI tokens as secrets. Grant only the access your repository needs. Do not post secret values in pull request comments or review replies.

Review current GitHub App permissions

Set up your workspace

Sign in

Select Continue with GitHub. Arcanist opens the workspace assigned to you. If you sign up on your own, Arcanist creates a workspace for you. There is no separate form for a workspace name.

If someone invited you, open their invite link and sign in with GitHub. You join that workspace.

Connect repositories

The onboarding page starts with Connect your repositories. Select Choose repositories on GitHub. Install the Arcanist GitHub App or change which repositories it can access. Then return to Arcanist and select Check again.

If a repository is missing from the list, check two things. You need write, maintain, or admin access on GitHub. The GitHub App must have access to the repository.

Organization approval

Some GitHub organizations require an administrator to approve new apps. Arcanist tells you when approval is needed. Review current GitHub App permissions, ask an organization admin to approve the app, then return and select Check again.

Single sign-on

If your organization uses single sign-on (SSO), GitHub can hide its repositories until you authorize. Select Authorize with GitHub, complete the organization step, then return and select Check again.

Invite teammates

Open Settings, then People. Select Invite teammates and Generate invite link. Anyone who opens the link and signs in with GitHub joins the workspace. The invite window shows when the link expires. A new link replaces the old one.

Know the roles

Workspace admins manage people, roles, billing, and workspace review defaults. Members can prepare repositories they can write to, start reviews, and manage their own CLI tokens.

Next step

After GitHub access is ready, continue to Prepare repositories. A connected repository is not ready for reviews until its status is Ready.

Prepare repositories

Why preparation matters

Before a review, Arcanist builds an environment: a private copy of your repository with everything needed to run its code. Preparation runs in the background. You can leave the page and follow progress under Environments.

Choose a setup type

On a Team workspace, select up to 20 repositories per batch. Each gets its own environment unless you choose Prepare repositories together. Starter supports one repository. Upgrade to Team for more.

On a Team workspace, select Prepare repositories together when several repositories must build, run, or test together. Choose the primary repository, then add up to seven related repositories under the same GitHub owner. Arcanist places them side by side in one environment. Pull requests on the primary repository trigger reviews. Select Prepare in separate environments instead to go back.

Start preparation

During onboarding, choose repositories and start preparation on the same page, then select Continue to reviews when ready. Later, open Environments and select Prepare repositories.

Read the status

Preparing

Arcanist is learning the repository, installing or starting the application, checking the setup, building the environment, or confirming that it runs. You do not need to do anything unless the status changes.

Ready

Arcanist can run code for reviews of this repository.

Needs your input

Select Add credentials or Answer question. Required credentials must be provided before setup can finish. Optional credentials can be skipped. If you cannot provide a requested secret, select I can't provide these so setup can continue without it.

Secret values are stored securely. Arcanist never shows them in the browser after you save them.

Waiting for Arcanist

Arcanist is working on a setup issue on its side. Watch Environments for the next status. Do not retry while this status is shown.

Setup stopped

Select Try again. If the repository lost GitHub App access, select Review GitHub access instead, fix access, and return.

When setup asks a question

Select Answer question, enter the information requested, and select Send. Preparation continues with your answer.

When you are done

Do not start the first review until the primary repository shows Ready. If related repositories are part of one application, confirm that the multi repository environment lists all of them.

Configure reviews

Start with manual reviews

Manual reviews are the safest way to test a new setup. Open Reviews and start one pull request, or comment @tryarcanist /review on GitHub. Turn on automatic reviews after the result looks useful.

Automatic reviews

Workspace admins open Settings, then Reviews. One switch turns on automatic reviews for new pull requests in every repository.

While the switch is on, admins can add Skip rules. Arcanist does not start an automatic review for a pull request that matches a rule:

Skip rules affect automatic reviews only. A workspace member can still start a manual review.

Review access

A person who starts a manual review must be an active workspace member and have write, maintain, or admin permission on the repository.

Use credentials carefully

A review can use your stored credentials only when the person who requested it is still a workspace member with write access to the repository. Pull requests from a fork (a copy of your repository owned by someone else) do not get your credentials when the application starts.

Check the effect

After you change a default, open a test pull request that matches the rule. Confirm that the review starts or stays excluded as expected. Manual review stays available when you need it.

Run and read reviews

Run your first review

Open Reviews. On your first visit, the page can suggest a pull request. Select Review this PR. To review another pull request, choose it from the dropdown on Reviews, or comment @tryarcanist /review on that pull request in GitHub.

From GitHub

Comment @tryarcanist /review on the pull request. Add a pull request URL from the same repository to review that pull request instead. Other text after the command is ignored.

With automatic reviews

When automatic reviews are on, Arcanist starts after a matching pull request is opened. Branch and bot rules decide whether it starts. A draft pull request is reviewed when it is marked ready for review.

Read the merge recommendation

Ready to merge

No finding blocks the merge. Read any findings below the recommendation. Ask for another review if the code changes.

Ready to merge with findings

Arcanist found issues that do not block the merge. Decide when to address them.

Hold off on merging

Arcanist found at least one issue serious enough to fix before merging.

Read each finding

A finding tells you the problem, the affected code, why it matters, and a specific fix. It can also include a prompt you can paste into a coding assistant.

A finding either blocks the merge or does not. The merge recommendation reflects blocking findings. On GitHub, read each finding's problem and fix. Use the app or the CLI if you need a per-finding blocks-merge label.

Each finding explains the problem and the suggested fix. The review summary can include a Ruled out section for attacks Arcanist tried and disproved. Use the recommendation and each finding to decide what to fix.

If a finding is wrong or lacks context, reply to its GitHub thread with the missing information. Resolve the thread when your team has decided. Run Arcanist again if new code changes the result.

Check the commit

The review names the exact commit it checked. If you push a fix, comment @tryarcanist /review again or start another review in the app. Read the new result against the latest code.

What Arcanist posts

Arcanist posts a GitHub review with its summary, recommendation, findings, and evidence. It does not approve the pull request or request changes for you.

Use Arcanist from the command line

Arcanist also has a command-line tool for terminals and automation such as CI. Create a token in the app under Settings > CLI. Then follow the CLI guide on npm. Run arcanist --help for the full list of commands.