> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opslane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Integration: Install and Configure Opslane

> Connect Opslane to your GitHub repos, configure access, set up branch protection, and learn how PR events trigger automated browser test runs.

The Opslane GitHub App is the only connection you need to start getting real-browser test results on your pull requests. Once installed, Opslane listens for PR activity in the repos you choose, spins up a browser run automatically, and posts results back as a PR comment — no other configuration required.

## Install the GitHub App

<Steps>
  <Step title="Start the installation">
    Go to [app.opslane.com/auth/github/login](https://app.opslane.com/auth/github/login) and click **Install GitHub App**. GitHub will prompt you to sign in if you aren't already authenticated.
  </Step>

  <Step title="Choose an account">
    Select the GitHub account or organization where you want to install Opslane. If you want to use Opslane across multiple organizations, you can install it separately on each one.
  </Step>

  <Step title="Select repositories">
    Choose which repositories Opslane can access. You have two options:

    * **All repositories** — Opslane monitors every repo in the account, including new ones created in the future.
    * **Only select repositories** — Pick specific repos by name. You can add more later from your GitHub App settings.

    <Tip>
      Start with a single repository to verify everything works before expanding access to your full organization.
    </Tip>
  </Step>

  <Step title="Authorize and finish">
    Click **Install & Authorize**. GitHub redirects you back to Opslane, where your connected repositories appear in the dashboard. Opslane is now active and will pick up the next pull request you open.
  </Step>
</Steps>

## Repository access and permissions

Opslane requests only the permissions it needs to do its job. The table below explains what each permission is used for.

| Permission          | Access level | Why Opslane needs it                                       |
| ------------------- | ------------ | ---------------------------------------------------------- |
| Pull requests       | Read & write | Read PR metadata to trigger runs; post the results comment |
| Commit statuses     | Read & write | Set a passing or failing GitHub status check on the PR     |
| Repository contents | Read         | Read the repo to identify the deployment URL for the run   |
| Metadata            | Read         | Required by GitHub for all apps                            |

<Note>
  Opslane does **not** read your source code to run tests. It uses your running app's URL — typically a preview deployment — as the test target. Source code access is limited to reading deployment configuration where necessary.
</Note>

## How PR events trigger runs

Opslane subscribes to GitHub's `pull_request` webhook and starts a browser run whenever any of these events occur:

* **`opened`** — a new pull request is created
* **`synchronize`** — a new commit is pushed to an open pull request
* **`reopened`** — a previously closed pull request is reopened

When one of these events fires, Opslane:

1. Reads the PR's head commit and associated deployment URL
2. Spins up an ephemeral sandbox with a real browser
3. Crawls the app at that URL and runs flow verification
4. Posts a PR comment with pass/fail status, screenshots, and a video
5. Sets a GitHub commit status check to `success` or `failure`

<Info>
  Each run is tied to the specific commit at the time the event fired. Pushing a new commit to the same PR starts a fresh run for that commit.
</Info>

## PR comment and status checks

After every run, Opslane posts a comment on the pull request from the `opslane-bot` account. The comment includes:

* A **pass or fail** summary for the run
* **Screenshots** captured during the browser session
* A **video** of the full run for debugging regressions
* A link to the full run details in the Opslane dashboard

Alongside the comment, Opslane sets a **GitHub commit status check** named `opslane / browser-test`. This status appears in the PR checks section and can be used with branch protection rules to block merges when regressions are detected.

## Block merges with branch protection

To enforce that regressions cannot be merged, configure GitHub branch protection to require the Opslane status check to pass.

<Steps>
  <Step title="Open branch protection settings">
    In your GitHub repository, go to **Settings → Branches**. Under **Branch protection rules**, click **Add rule** or edit an existing rule for your default branch (typically `main` or `master`).
  </Step>

  <Step title="Enable required status checks">
    Check **Require status checks to pass before merging**, then check **Require branches to be up to date before merging**.
  </Step>

  <Step title="Add the Opslane check">
    In the search box that appears, type `opslane` and select **opslane / browser-test** from the results.

    <Warning>
      The status check only appears in the search results after Opslane has run at least once on a pull request in that repository. Open a test PR first if the check doesn't appear yet.
    </Warning>
  </Step>

  <Step title="Save the rule">
    Click **Create** or **Save changes**. From this point on, any PR where Opslane detects a regression will be blocked from merging until the check passes.
  </Step>
</Steps>

## Add or remove repository access

You can change which repositories Opslane has access to at any time.

**To add a repository:** Go to your GitHub account's **Settings → Applications → Installed GitHub Apps**, find Opslane, click **Configure**, and add the repo under **Repository access**.

**To remove a repository:** Follow the same path and remove the repo from the access list. Opslane immediately stops receiving webhook events for that repo.

## Uninstall the GitHub App

To fully remove Opslane from a GitHub account or organization, go to **Settings → Applications → Installed GitHub Apps**, find Opslane, click **Configure**, and then click **Uninstall**. This revokes all permissions, stops all webhook deliveries, and removes Opslane bot from any pending PR checks.

<Warning>
  Uninstalling the app does not delete your Opslane account or historical run data. To delete your account, contact Opslane support.
</Warning>