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

# Connect GitHub

> Install the BuildPixel GitHub App, scope it to specific repos, and you're ready to map projects.

GitHub integration uses the **GitHub App** model — installed to your GitHub user or org, scoped to specific repos, no personal access tokens involved.

## Install the App

<Steps>
  <Step title="Open Settings → Integrations">
    Click **Install GitHub App**. You'll be redirected to GitHub.
  </Step>

  <Step title="Pick where to install">
    GitHub asks where you want the App installed. Pick your user (for personal repos) or your studio's GitHub org.
  </Step>

  <Step title="Scope it to specific repos">
    <Tip>Choose **Only select repositories** and pick the UE projects you want to build. Avoid granting "All repositories" unless you have a reason to.</Tip>
  </Step>

  <Step title="Confirm">
    GitHub redirects you back to BuildPixel. The installation is wired up to your org. You're now connected.
  </Step>
</Steps>

## What the App can see

The App requests the minimum it needs to build your code:

* **Contents: Read** — to clone the repo
* **Metadata: Read** — to list branches and detect `.uproject`
* **Pull requests: Read** — to attribute push-triggered builds to a PR

## Mapping a project

Once the App is installed, the project creation flow lists every repo it can see. Pick one, BuildPixel reads the `.uproject` from the default branch, and the project is created. See [Quickstart](/get-started/quickstart#3-map-your-project) for the full walkthrough.

If your `.uproject` lives more than 3 directories deep, set `uprojectPath` manually on the build setting.

## Push triggers

Build settings with `trigger: "push"` build automatically when a push to the tracked branch lands. The webhook URL is preconfigured at App install time — no setup in your repo needed. See [Triggers](/builds/triggers).

## Disconnecting

Two ways:

* **Uninstall the App** at `github.com/settings/installations` — revokes access immediately.
* Or call `DELETE /organizations/:id/integrations/github` — clears the link on the BuildPixel side without uninstalling.

Existing GitHub-backed projects will fail builds until you reconnect.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The repo picker is empty">
    The App is installed but no repos were granted. Go to `github.com/settings/installations`, find BuildPixel, click Configure, and add repos.
  </Accordion>

  <Accordion title="Engine version shows 'Unknown'">
    Your `.uproject` probably uses a custom engine path. Set `ueVersion` explicitly on the build setting. See [Engine versions](/builds/engine-versions).
  </Accordion>

  <Accordion title="Build setting won't trigger on push">
    Check that `trigger` is `"push"` (not `"manual"`), the branch name matches exactly, and the App still has access to the repo.
  </Accordion>
</AccordionGroup>