Connect GitHub
On this page
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
In the dashboard, open Settings → Integrations and click Connect GitHub.
GitHub opens in a popup. Choose the account or organisation, select the repositories OPVS may
use, and install.
The popup closes itself. The card now reads Connected: \<account\>, 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
Open the project, then Settings → Code.
Under Repository from GitHub, pick the repository. This fills the URL, the default branch and
the credential builds push with.
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:
opvs ship connect --project <project-id> # prints the install link and the link-existing link
opvs ship status --project <project-id> # read the Ship app lineCheck it worked
opvs ship status --project <project-id> 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 |
| Nothing installed for this workspace | Install the app, step 1 |
| The app is installed but not on the project's repository | Grant the repository on GitHub, then pick it in the Code tab |
| Someone uninstalled the app on github.com | Click Connect GitHub again |
| 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, Set up your factory step 6.