# Connect GitHub

At the end of this guide Volobox reaches your GitHub repositories through a GitHub App that belongs to your own organization, and the repositories you choose are registered so projects can link them. Because the app is yours, it sees only the organizations you install it on. An administrator who may open integration settings and holds **Manage integrations** can do it; Admins have both.

## Before you begin

- A Volobox account with the integrations permission under **Organization settings** (to open the tab) and **Manage integrations** (to create, verify or disconnect the app).
- A GitHub account that can create a GitHub App, and that can install apps on the GitHub organization whose repositories Volobox should use.
- A free app name. GitHub requires app names to be unique across all of GitHub, so include your company name if the default is taken.

## Create the GitHub App

1. Open **Admin** on the left activity rail, then **Settings**, and select the **Integrations** tab of **Organization Settings**.
2. Optionally set **App name**.
3. Set **Organization** to the GitHub organization that will own the app. Volobox creates a private app, and GitHub lets a private app be installed only on the account that owns it.
4. Select **Create GitHub App**. Volobox hands GitHub a pre-filled form.
5. On GitHub, confirm the name and create the app. GitHub returns you to Volobox, which stores the app's credentials encrypted.

> **Tip:** If your deployment was set up with GitHub credentials already, the tab offers **Import configured app** instead of **Create GitHub App**. Prefer it: it keeps the same app, so connected organizations, registered repositories and everyone's personal GitHub connections are unaffected.

## Install the app and register repositories

1. Select **Install on an organization** and choose which repositories the app may access.
2. Back in the GitHub App section, select **Sync organizations**. The organization appears in the list below the app.
3. Select **Register repositories**. It opens **Code**, where **Register repository** lets you pick the organization and one of its repositories. The name, URL and default branch come from GitHub.
4. Repeat **Register repository** for each repository projects should use.

![Organization Settings, Code tab, Repositories: the meridian-works GitHub organization the GitHub App is installed on, the Azure DevOps organization, and the registered repositories from GitHub, Azure DevOps and GitLab with their default branches.](https://volobox.io/docs/images/github-integration.light.webp)

*Organization Settings, Code, Repositories: the GitHub organization the app is installed on, and the registered repositories with their code host, default branch and projects.*

A project then links the repositories it works on: in the project's **Settings**, open **Repositories** and select **Link repository**. That is also where a project sets up GitHub issue tracking.

## Connect your own GitHub account

The app gives Volobox access. Each person also connects their own GitHub account, so their pull request reviews, comments and merges, and the commits of their coding-session turns, carry their own GitHub identity.

1. Open your avatar menu, select **Settings**, then the **Integrations** tab of **Personal Settings**.
2. Select **Connect GitHub** and approve the authorization on GitHub.

GitHub returns you to the Integrations tab, which shows **Connected as** your GitHub login.

## Check that it works

1. In **Organization Settings**, on the **Integrations** tab, select **Verify**. Volobox asks GitHub what the app can actually do and compares it with what this version of Volobox needs.
2. If something is missing, the page lists the exact permissions and events. Grant them on GitHub, then accept the update prompt on each installation.
3. Open **Code**: your organization and its registered repositories are listed.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| **Verify** reports missing permissions | Volobox cannot grant itself access to your app. Add the permissions on GitHub, then accept the change on each installation. |
| The page warns the app is out of date | The app was created by an older Volobox version. Select **Verify** to see what is missing, add it on GitHub, accept it on each installation, then select **Verify** again. |
| The page warns that no webhook secret is stored | Incoming GitHub deliveries are rejected. Disconnect, and create the app again. |
| GitHub's **Recent Deliveries** shows `202`, but a pull request or branch has not changed yet | Volobox stores each delivery first and applies it in the background. **Redeliver** a delivery that kept failing on GitHub to queue it again; the periodic sync catches up either way. |
| The app was created but Volobox sees no repositories | Creating the app grants access to nothing. Install it on an organization and select **Sync organizations**. |
| Someone's reviews stop being attributed to them after an app change | Their personal GitHub connection belongs to the old app. They reconnect in **Personal Settings** under **Integrations**. |

> **Warning:** **Disconnect** deletes the stored credentials, and nothing can reach GitHub until a new app is connected and installed. Repositories stay registered, but do not disconnect to "reset" an app that works.

## Next steps

- [From a task to a pull request](/docs/task-to-pull-request)
- [Write a preview manifest](/docs/write-preview-manifest)
- [Coding sessions](/docs/coding)
- [Integrations](/docs/integrations)
