Skip to content

Git

GitHub

Connect the CirCI GitHub App to report builds as checks on pull requests, and review from GitHub.

Every build of a linked project shows on its pull request as a check named CirCI / <build name>, with Approve and Reject buttons, plus one summary comment that CirCI edits in place. People can also review by replying /circi approve or /circi reject. It works through a GitHub App that belongs to your CirCI instance.

You get Where
A check per build name, with Approve and Reject buttons The pull request's Checks tab and merge box
One summary comment per pull request The pull request's conversation
/circi approve, /circi reject, /circi rerun A comment on the pull request
One help comment when a command or button can't be used The same conversation, edited in place

Steps 1 and 2 are done once per instance by an instance admin; steps 3 and 4 by an owner or admin of each workspace.

  1. Create the GitHub App on the instance, by one click or by hand (below).
  2. Install the App on your GitHub account or organization.
  3. In Workspace settings › Integrations › Add integration, pick GitHub. If the instance has an App, the dialog sends you to GitHub to install it, and the return connects that installation to this workspace.
  4. Link each project to a repository (see Link a project to a repository), then mark the check as required in the repository's branch protection if it should block merging.

Open Instance settings and find the GitHub App section. It shows a badge: Not set up, Environment or Created here.

  1. Optionally change the App name (up to 34 characters, unique across GitHub; the default is CirCI (<your host>)), and enter a GitHub organization if the App should belong to one. Leave it empty for your own account.
  2. Press Create GitHub App. GitHub opens with the App's name, address, permissions and events filled in.
  3. Confirm on GitHub. GitHub sends you back to CirCI, which exchanges the one-time code for the App's credentials and stores them encrypted on the instance. The running server, webhook handler and worker use the App at once.
  4. Install the App on your account or organization when GitHub offers it.

The link from GitHub works once. If creation fails, start again from the button. CirCI refuses plain http addresses other than localhost, because GitHub only delivers webhooks to https; on localhost it works for trying things out but warns that GitHub can't reach it.

If GITHUB_APP_* is set in the environment it always wins: the instance page then only shows the App (ID and slug) and hides the create button. An App created from the page is stored in the instance database, and several replicas pick it up when they restart. Creating the App from the page is the alternative to setting the variables.

The permissions are the smallest set that works: Checks for the check run and its buttons, Pull requests for the summary comment and its reactions, Metadata because GitHub always grants it.

  • If the instance has an App, Add integration sends you to GitHub to install it, and the return connects that installation to this workspace.
  • If the App was installed from GitHub itself, the return lands on a Connect GitHub page where you choose the workspace.
  • If the instance has no App yet, an instance admin sees a prompt to set one up, and anyone else is told to ask an admin.

CirCI verifies the installation with GitHub (it requests a token and lists the repositories), so the App must really be installed there. An installation belongs to one workspace of the instance.

Each project reports to one repository. There are four ways to link:

  • The integration's page. Open the GitHub integration under Integrations and choose a repository for each project. The list comes from the installation; you can also type owner/name.
  • The project's settings. The Repository row shows the link, and Remove takes it away.
  • Import from GitHub. On the projects page, owners and admins of a workspace with a GitHub connection can import repositories as new projects. Each picked repository becomes a project named after it (acme/web-app becomes web-app, or acme-web-app if that address is taken). Up to 50 repositories can be imported at once, and you become a member of each. The imported projects get no CI token until you issue one in their settings.
  • The command line, run on the server:
Terminal window
circi admin github link --org acme --project web --repo acme/web --installation 12345678
circi admin github unlink --org acme --project web

The installation ID is the number at the end of the installation's settings address on GitHub. The command checks it with GitHub before saving anything. Linking from the project's settings page records the installation without that check, so prefer the integration's page when you can.

One check per build name, called CirCI / <build name> (for example CirCI / default). It's in progress while screenshots are processed ("Processing screenshots…"), then ends as one of:

Situation Check title Result
No visual changes No visual changes Passes
Changes await review 3 changed · 1 added: review required Action required, or passes when the project doesn't block merging
Approved Changes approved (3 changed · 1 added) Passes
Rejected Changes rejected (3 changed · 1 added) Fails
Only flaky screenshots changed Only flaky screenshots changed (2 changed) Passes when the project doesn't hold merges for flaky ones
Some screenshots couldn't be read 1 screenshot couldn't be read Fails when the project blocks merging, neutral otherwise, whatever was approved. Upload the build again to clear it
Processing failed Processing failed, with the error Fails, or neutral when the project doesn't block merging
No changes, but the project approves by hand No visual changes: approval required Action required, with an Approve button

The counts in a title read changed, added, removed and couldn't be read, joined with a middle dot, for example 3 changed · 1 couldn't be read. While a build waits, the check carries Approve and Reject buttons, and approving in the dashboard or on GitHub updates the check within seconds, with no CI re-run.

A check that waits says what to do next: "Approve or reject it here or reply /circi approve or /circi reject on the pull request, or open the build to see it." The sentence about replying is left out for a build with no pull request.

One comment per pull request, edited in place whenever a build changes, with a row for each build name. This is its text:

### CirCI visual tests
| Build | Status | Changes | Review |
| --- | --- | --- | --- |
| [default](https://circi.example.com/acme/web-app/builds/42) | Changes detected | 3 changed · 1 added | [Review](https://circi.example.com/acme/web-app/builds/42) |
| [mobile](https://circi.example.com/acme/web-app/builds/43) | No changes | — | — |
**Hosted sites for this commit**
- [Storybook](https://circi.example.com/…)
Review the builds in CirCI (the links above), or reply `/circi approve` or `/circi reject` here. `/circi rerun` processes them again.

In the real comment each status starts with a symbol: a yellow circle for changes, a check mark for no changes or approved, a cross for failed or rejected, an hourglass while processing. Once someone decides, the review cell reads "Approved by Ada Lovelace", and when a build's screenshots were decided differently, the detail follows, for example "(2 approved · 1 pending)". A build with screenshots that couldn't be read shows "1 screenshot couldn't be read" in that cell instead of a review link. The closing line changes to "Reply /circi approve, /circi reject or /circi rerun to act on the latest builds." when nothing waits for a decision.

The Hosted sites for this commit list appears only when the project hosts static sites, and names the sites of the newest commit; see Hosted sites.

Reply on the pull request with one of these on a line of its own:

Command What it does
/circi approve Approves the newest build of each build name on the pull request
/circi reject Rejects them
/circi rerun Processes the builds again, for example after changing a threshold

CirCI reacts to the comment with a thumbs-up when it acted. When it didn't, it reacts with a thumbs-down and says why in one help comment per pull request. That comment is found again by a hidden marker and edited in place, so repeated mistakes never pile up comments. It carries the latest reason:

Reason What the help comment says
No build yet "There's no CirCI build for this pull request yet. Reply again once your tests have uploaded screenshots."
Still processing "The latest build is still processing. Reply /circi approve again when its check finishes."
Processing failed "The latest build failed, so there's nothing to approve. /circi rerun processes it again."
Nothing to decide "Nothing to approve: the latest build has no visual changes, and this project doesn't require approval."
You aren't linked "I couldn't tell who you are in CirCI. Sign in at PUBLIC_URL with GitHub, using a member of this project's workspace, then try again." (The real text also names the page where the account is linked.)

The command's name replaces "approve" in the replies (reject, rerun). Edited comments don't repeat the action.

A button on the check that can't act answers on the check itself: a note titled Nothing to decide with the same reasons, or Not allowed with the linking help (which is also posted in the help comment when the build has a pull request).

To block merging, mark the check as required in the repository's branch protection. Then, on the project's Settings page, the Merge gate section controls what the check says while changes wait:

  • Unreviewed changes block merging: on, the check stays at action required until someone approves. Off, it passes with a "changes to review" summary.
  • Flaky-only changes block merging: whether changes to flaky screenshots hold the pull request.
  • Approve default-branch builds automatically: needs an approved baseline to compare with, so a project's first build is always reviewed.

Screenshots that couldn't be read follow Unreviewed changes block merging as well, and the check still says how many couldn't be read. Who blocks the merge, the check or the CI job, and what --wait exits with, is explained in How a build flows.

The first build of a project has nothing to compare with, so every screenshot is new and waits for review.

Commands and the check's buttons are accepted from a person who has linked their GitHub account in the Signed in with section of their CirCI Profile and who can see the project (a project member, or an owner or admin of its workspace). CirCI matches the GitHub account ID, never the email address. Anyone else gets the linking help above. Linking needs GitHub sign-in to be configured on the instance.

Decisions made this way appear in the build's activity as coming from a GitHub comment (github-comment) or a GitHub check (github-check).

What you see Why, and what to do
The dialog says Not set up on this server The instance has no GitHub App yet. An instance admin creates one under Instance settings
No check appears on the pull request The project isn't linked to this repository. Check Repository in the project's settings, and that the App is installed on it
The check never moves from "Processing screenshots…" The worker isn't running or the build is stuck. See Instance administration for the worker's health
/circi approve gets a thumbs-down Read the help comment: it names the reason (see the table above)
The help comment says it can't tell who you are Link your GitHub account in Profile › Signed in with, using an account that belongs to the project's workspace
The integration shows needs attention GitHub removed or suspended the installation, or rejected the credentials. Reinstall the App; an unsuspend or a fresh install clears the flag
Buttons or comments do nothing at all GitHub's webhook deliveries are failing. In the GitHub App's Advanced page, look at Recent deliveries, and check that PUBLIC_URL is reachable from GitHub and the secret matches

The App's webhook is the one entry point. CirCI verifies the signature and handles each delivery once.

  • pull_request opened, reopened or synchronized: remembers the author, which replaces the username the CI sent, and gives builds their pull request number.
  • pull_request closed or merged: closes the open review requests on that pull request's builds and clears their "please review" notices. The builds keep their own review status.
  • check_run with a button press: Approve or Reject.
  • issue_comment created on a pull request: the /circi commands. Comments by bots are ignored.
  • installation deleted or suspended: flags the connection as needing attention. Created or unsuspended clears it.

Not yet verified against github.com.