GitHub App
Introduction
The GitHub App page lets you register a GitHub App for your Vito instance. A GitHub App is a more secure way to connect source control than personal access tokens or deployment keys: it uses short-lived, per-repository tokens and lets organizations install it to grant access to their repositories.
Once registered, GitHub App installations appear as source controls that your sites can deploy from.
GitHub App deployments no longer use deployment keys. Instead of adding an SSH deploy key to each repository, Vito injects a short-lived (1 hour), per-repository token at deploy time. The token only exists in the environment during the deployment and is never written to disk.
Registering the app
You register the app once per Vito instance, using one of two methods.
Automatic registration
Vito generates a GitHub App manifest and hands off to GitHub, which creates the app and returns its credentials (ID, private key, webhook secret) automatically. This is the easiest method and sets up webhooks so installs and uninstalls are detected instantly.
Automatic registration relies on GitHub being able to reach your instance via webhooks, so it only works when Vito is publicly accessible on the internet.
Manual registration
For instances that are not publicly reachable (for example, local or private installations, or hosts
on .test / .localhost domains), Vito guides you through creating the app manually on GitHub and
entering its details. This works without public access, but webhook-driven updates will not function
(see Keeping installations in sync).
Open Admin > GitHub App, select the Manual tab, and follow the two steps.
Step 1: Create the app on GitHub
Click Open GitHub App creation page to open GitHub's "Register new GitHub App" form in a new tab. Vito displays a set of copyable values to paste into the matching fields on GitHub:
| Vito field | Where it goes on GitHub | Notes |
|---|---|---|
| Homepage URL | Homepage URL | |
| Callback URL | Callback URL | |
| Setup URL (post installation) | Setup URL | Tick Redirect on update |
| Webhook URL | Webhook URL | Leave Active checked |
| Webhook secret | Webhook secret | Generated by Vito; paste it in. The same value is pre-filled in Step 2. |
Set the following permissions and events:
- Repository → Contents: Read-only
- Repository → Metadata: Read-only (auto-selected by GitHub)
- Subscribe to events: Push
- Where can this GitHub App be installed?: Any account (required so it can be installed on organizations)
The Installation and Installation repositories events are delivered automatically to every GitHub App that has a webhook URL. They are not in the "Subscribe to events" list and do not need to be selected. Vito uses them to keep installed accounts and repositories in sync.
After saving the app, on its settings page:
- Generate a Client secret.
- Scroll to Private keys and Generate a private key (GitHub downloads a
.pemfile). - Note the App ID shown at the top of the page, and the app's page URL from the address bar
(for example
https://github.com/apps/vito-yourhost).
Step 2: Paste the credentials into Vito
Back on the GitHub App page in Vito, fill in the form with the values from Step 1 and save:
- App ID - the numeric App ID from the app's settings page.
- Display name (optional) - a friendly name for the app.
- App page URL - for example
https://github.com/apps/your-slug. - Client ID - from the app's settings page.
- Client secret - the client secret you generated.
- Webhook secret - pre-filled with the value from Step 1; leave it as-is unless you used a different value on GitHub.
- Private key (PEM) - paste the entire contents of the downloaded
.pemfile (including the-----BEGIN ... PRIVATE KEY-----lines).
Click Save GitHub App. Once saved, the app is configured and you can install it on a GitHub organization and sync its installations, just as with automatic registration.
Connecting repositories
After the app is registered, organizations and users install it on GitHub and choose which repositories to grant access to. Each installation is imported into Vito as a source control record, and its repositories and branches become available when creating or deploying sites.
Keeping installations in sync
When Vito is publicly reachable, webhook events keep installations up to date in real time. Vito also runs a background sync every 4 hours to reconcile its records with GitHub.
If your instance is not publicly reachable, a warning is shown on the page. Installs and uninstalls are then only picked up on the 4-hour sync, or when you click the Sync button manually.
Removing the app
You can remove the GitHub App from Vito. GitHub App source controls cannot be deleted from within Vito directly while installed; uninstall the app from GitHub instead, and Vito will reconcile the change.