Administration

Guide

Connect GitHub

Create your organization's own GitHub App from Volobox, install it on your GitHub organizations and register the repositories projects will use.

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, 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

SymptomFix
Verify reports missing permissionsVolobox 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 dateThe 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 storedIncoming 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 yetVolobox 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 repositoriesCreating 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 changeTheir 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