# Connect GitHub Source: https://opvs.ai/docs/factory/connect-github > Install the OPVS Builder GitHub app, pick a repository per project, and connect the ship line. Connect GitHub so builders can clone your repository, push their branches and open pull requests, and so the ship line can merge. You connect once for the workspace, then pick a repository per project. **You need:** to be a workspace admin, and admin rights on the GitHub account or organisation that owns the repository. ## Why an app, not a personal token OPVS Builder app Personal access token Pull request author The app (a bot) The person who made the token Reach Only the repositories you select Every repository that person can reach Lifetime Minted per build, an hour at most Until revoked Who can revoke You, from your GitHub settings The token's owner A project can still build with a personal token saved under Integrations; the Code tab then says the pull requests will carry that person's name. ## 1. Install the app 1. In the dashboard, open **Settings → Integrations** and click **Connect GitHub**. 2. GitHub opens in a popup. Choose the account or organisation, select the repositories OPVS may use, and install. 1. The popup closes itself. The card now reads **Connected: \**, with the repositories the app can reach. The app asks for exactly three repository permissions: **Contents** (read and write, to clone and push), **Pull requests** (read and write, to open them) and **Metadata** (read-only, required by GitHub). Nothing at the organisation or account level, and no access to workflow files. **If the app is already installed on that GitHub account,** click **Link an existing installation** instead. GitHub would otherwise show its Configure page and never return to OPVS. ## 2. Pick the repository for a project 1. Open the project, then **Settings → Code**. 2. Under **Repository from GitHub**, pick the repository. This fills the URL, the default branch and the credential builds push with. 1. Check the notice under the credential picker: it says whose name will be on the pull requests. If the repository you want is not in the list, the app was not granted it. Add it on GitHub (the card's **Manage on GitHub** button), then pick again. ## 3. Connect the ship line The ship line uses the same app to merge: ```bash opvs ship connect --project # prints the install link and the link-existing link opvs ship status --project # read the Ship app line ``` ## Check it worked `opvs ship status --project ` prints the repository and the Ship app as `connected`. On the API, `GET /api/v1/github-app/status` returns the workspace's connection. ## If it did not work You see When What to do **Connect GitHub** is missing The app is not available on this platform yet Use a personal access token under Integrations meanwhile `not connected` Nothing installed for this workspace Install the app, step 1 `repository missing` The app is installed but not on the project's repository Grant the repository on GitHub, then pick it in the Code tab `installation removed` Someone uninstalled the app on github.com Click **Connect GitHub** again `suspended` The installation is suspended on github.com Unsuspend it with **Manage on GitHub** GitHub says "This GitHub App must be configured with a callback URL" on **Link an existing installation** A known issue on our side (6 Nov 2026) Uninstall the app on github.com, then use **Connect GitHub** The build pushes its branch, then fails opening the pull request The credential cannot write pull requests Use the app, or give the token pull-request write access Related: [Projects](/developers/factory/projects), [Set up your factory](/developers/factory/set-up) step 6.