Obvious/Help Center

Install the GitHub App

Published May 8, 2026 · Last updated June 18, 2026 · 5 min read

Use the Obvious GitHub App to give Autobuild access to your repositories. Once installed, agents can read code, open pull requests, and run automated workflows against any repo in your GitHub organization.

Before you begin

Before connecting GitHub, make sure you have:

  • A workspace in Obvious with workspace admin or owner permissions.
  • A GitHub account with permission to install GitHub Apps on the organization or personal account that owns your repositories.

If you're looking for more information about how Autobuild works before connecting a repository, see What is Autobuild?.

Overview

Connecting GitHub to Autobuild is a two-part process. First, you install the Obvious GitHub App on your GitHub organization — this grants Autobuild permission to open PRs, read repository contents, and receive webhook events. Then, back in Obvious, you import the specific repositories you want agents to work in.

After completing these steps, you'll have at least one repository visible in Settings under Repo sandboxes, with agents able to open pull requests against it.

Install the GitHub App

The GitHub App connects Obvious to your GitHub organization. If no GitHub App has been connected yet, you'll land on the Autobuild home empty state, which shows a Connect GitHub panel with a prompt and an Install GitHub App button.

  1. Click Install GitHub App. The button changes to Opening GitHub… while it prepares the redirect.
  2. A new browser tab opens to GitHub's App installation page. Select the organization or personal account where your repositories live, then choose which repositories to grant access to — you can grant access to all repositories or select specific ones.
  3. Click Install on GitHub to confirm. GitHub redirects you back to Obvious automatically after installation completes.

Note: If the tab doesn't open, check that your browser isn't blocking pop-ups from Obvious.

Import repositories

After GitHub redirects you back, Obvious shows the repositories available from your installation — you're still on the Autobuild home.

  1. Confirm your GitHub organization name and the count of repositories available (for example, "yourorg · 12 repos").
  2. Use the Search repositories... field to filter if you have many repos.
  3. Under the Available header, check the boxes next to the repositories you want to import.
  4. To select all visible repositories at once, use the checkbox next to the Available label.
  5. Click Import. The button changes to Importing… while the import runs.
  6. Imported repositories appear in the Repositories list once the process completes.

Set up a repo sandbox

Importing a repository makes it available to Autobuild, but agents need a sandbox — a pre-built environment where they can run code — before they can open pull requests. You provision sandboxes from the Repo sandboxes section of settings.

  1. In settings, scroll to Repo sandboxes.
  2. If no sandboxes exist yet, you'll see: "No repo sandboxes configured yet. Use 'Add another sandbox' to browse repositories from your GitHub installation and choose resources before creating one."
  3. Click Add another sandbox.
  4. Use Search owner/repo… to find your imported repository.
  5. Click the repository name to select it.
  6. To use the larger sandbox, check Large sandbox. Leave it unchecked for the standard size.
  7. Click Create sandbox. The button changes to Creating… while provisioning starts.

How to confirm it worked

When setup is complete, your repository appears in Repo sandboxes with a Ready status badge. A Refresh button appears on the row when status is Ready. A Configure button appears when status is Ready or Failed.

At this point, agents can now open pull requests against that repository.

Troubleshooting

The "Install GitHub App" button doesn't open GitHub

Your browser may be blocking the pop-up. Allow pop-ups from Obvious in your browser settings and try again. If the issue persists, the Obvious GitHub App integration may not be fully configured — contact your workspace owner.

No repositories appear in the "Import repositories" panel

This usually means the GitHub App was installed with no repository access, or the installation was suspended. Return to GitHub, find the Obvious App under your organization's installed apps, and verify that it has access to at least one repository.

If necessary, edit the installation to grant access to specific repositories or to all repositories in the organization.

Sandbox status is stuck on "Pending" or shows "Failed"

If the status stays Pending for more than a few minutes, or shows Failed, use the action buttons on the row:

  • Retry — available when status is Failed. Attempts to rebuild the sandbox from scratch.
  • Configure — available when status is Ready or Failed. Opens the Configure sandbox dialog where you can set Install commands and adjust sandbox resources before retrying.
  • Remove — available when status is Pending or Ready or Failed. Clicking it shows a Confirm remove? prompt. Click again to confirm.

If Retry continues to fail, open Configure sandbox and add the install commands your repository needs before retrying.

"Couldn't reach GitHub installation" error

This error appears in the Add another sandbox panel when Obvious can't reach your GitHub installation. Verify that the GitHub App is still installed and not suspended on your GitHub organization, then try again.

Next steps

With your repository connected and a sandbox ready, you can:

  • Open a project that contains a spec document and ask the Autobuild agent to build it
  • Add more repositories by clicking Add another sandbox again in settings
  • Configure sandbox resources or install commands at any time with the Configure button on a Ready sandbox row
Was this helpful?