# 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](/docs/4.x/settings/source-controls)
that your sites can deploy from.

:::info
**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.

:::warning
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](#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)

:::info
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:

1. Generate a **Client secret**.
2. Scroll to **Private keys** and **Generate a private key** (GitHub downloads a `.pem` file).
3. 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 `.pem` file (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.

:::info
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.