Install the GitHub App

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 in the repositories you connect.

Before you begin

Before connecting GitHub, make sure you have:

• Workspace admin access in Obvious.

• 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?.

Start setup

Autobuild has its own section in the sidebar, labeled Autobuild. On a workspace that hasn't set up Autobuild yet, a welcome page appears with the headline Set Up Your Software Factory and three steps: 01 Design, 02 Build, 03 Release. Select Set up Autobuild to start.

The button appears for workspace admins. If you don't see it, ask an admin to run setup.

Setup walks through five steps:

1. Connect a provider: install the Obvious GitHub App on your GitHub organization.

2. Add visual PR evidence: optional.

3. Choose repositories: select the repositories Autobuild can work in.

4. Setting up sandboxes: Autobuild prepares the sandbox environments agents use to run code.

5. Add skills or docs: optional.

Connect GitHub

The first step, Connect a provider, asks you to grant access to the organization where you want to do your best work.

1. Start the GitHub connection. A new browser tab opens to GitHub's App installation page.

2. 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. Select Install on GitHub to confirm. GitHub redirects you back to Obvious automatically after installation completes.

Obvious checks for the installation and continues to the next step when it appears. If the tab doesn't open, check that your browser isn't blocking pop-ups from Obvious.

After setup

When setup finishes, your repositories are connected. Agents can open pull requests against a repository once its sandbox shows Ready; you can check each sandbox's status from settings. Select Settings at the top right of the Autobuild home and open the Repos & Sandboxes tab.

With a sandbox Ready, you're set to start your first build. See Your First Initiative.

Manage repositories and sandboxes

Agents need a repo sandbox, a pre-built environment where they can run code, before they can open pull requests. Setup prepares sandboxes for the repositories you chose. To add another repository after setup:

1. Open the Repos & Sandboxes tab in settings.

2. Select Add sandbox.

3. Use the search field to find your repository, or paste a repository URL for Bitbucket or Azure DevOps.

4. Select the repository name.

5. To use the larger sandbox, select Large sandbox. Leave it unchecked for the standard size.

6. Select Create sandbox.

Connect one GitHub App to multiple workspaces

If your organization uses more than one Obvious workspace, for example separate workspaces for different teams or environments, you can connect the same GitHub App installation to each of them. Each connection is independent: each workspace chooses its own repositories and provisions its own sandboxes, and activity in one workspace does not affect another.

To connect an additional workspace, run through setup from that workspace. When GitHub asks to install the app, the existing installation is already present on your organization. GitHub will confirm and redirect you back to Obvious, where you can choose repositories and set up sandboxes as usual.

If you've connected the same GitHub App to multiple workspaces, repository access changes on GitHub apply to all connections.

Troubleshooting

GitHub doesn't open when you connect

Your browser may be blocking the pop-up. Allow pop-ups from Obvious in your browser settings and try again. If the issue persists, contact your workspace owner.

No repositories appear when you choose repositories

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, Ready, or Failed. Selecting it shows a Confirm remove? prompt. Select again to confirm.

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