Obvious/Help Center

Install the GitHub App

Published May 8, 2026 · Last updated May 12, 2026 · 6 min read

Before you begin

Before connecting GitHub, make sure you have:

  • A workspace in Obvious with at least workspace admin permissions (only workspace admins can manage Autobuild settings)

  • A GitHub account with permission to install GitHub Apps on the organization or personal account that owns your repositories

  • Read What is Autobuild? if you want background on how Autobuild uses repositories before you connect one

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.

By the end of this guide, you will have at least one repository visible in Settings under Repo sandboxes, with agents able to open pull requests against it.

  1. Navigate to Autobuild in your Obvious workspace.

If no GitHub App has been connected yet, you'll land on the Autobuild home empty state. It shows a Connect GitHub panel with:

  • A prompt: "Install the Obvious GitHub App to import repositories and enable automated PR workflows."

  • A button: Install GitHub App

Install the GitHub App

The GitHub App connects Obvious to your GitHub organization.

  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.

  3. Choose which repositories to grant access to — you can grant access to all repositories or select specific ones.

  4. 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. You'll see 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.

    • To select all visible repositories at once, use the checkbox next to the Available label.

  4. Click Import Selected (the button shows the count of selected repos, for example "Import 3 Selected").

  5. The button changes to Importing… while the import runs.

Once the import completes, the selected repositories move from Available to Imported, each showing a checkmark. You can close this panel and return to Autobuild Settings to continue.

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 the Settings tab, 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 CPU/memory resources before creating one."

  3. Click Add another sandbox (top-right of the section).

  4. The add panel expands below. Use Search owner/repo… to find your imported repository.

  5. Click the repository name to select it.

  6. On the right, configure resources:

    • vCPU — select a CPU count
    • RAM (GiB) — select a memory amount
    • Optionally check Large sandbox (16 vCPU, 32GB RAM) if your build requires more resources — this disables the individual pickers

  7. Click Create sandbox. The button changes to Creating… while provisioning starts.

The repository row appears in the sandbox list with a Pending status badge, then transitions to Building… as the snapshot is prepared. When it finishes, the badge shows Ready.

The sandbox build takes a few minutes. You don't need to stay on this page — the status updates automatically when you return.

How to confirm it worked

When setup is complete, you should see:

  • Your repository listed in Repo sandboxes with a Ready status badge

  • A Refresh button and a Configure button next to the repository row (Refresh appears only when status is Ready; Configure appears when status is Ready or Failed)

Agents can now open pull requests against that repository.

Troubleshooting

The Install GitHub App button does nothing, or the GitHub tab doesn't open

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.

After returning from GitHub, I don't see any repositories to import

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.

The sandbox is stuck in 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 (run during the snapshot build) and adjust vCPU and RAM (GiB) 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 (for example, npm install) before retrying.

I see "Could not load GitHub repositories. Check installation permissions and retry."

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?