# GitHub Template Sync

Allegro supports syncing templates from a GitHub repository. When connected, templates are automatically synced whenever commits are pushed to the configured default branch.

## How It Works[​](#how-it-works "Direct link to How It Works")

1. An organization admin installs the Allegro GitHub App on their GitHub account or organization.
2. After installation, the app links the GitHub App installation to the Allegro tenant.
3. The admin selects a repository and default branch to sync from.
4. On every push to that branch, a sync job is queued to update templates from the repository.

***

## Setting Up the GitHub App[​](#setting-up-the-github-app "Direct link to Setting Up the GitHub App")

### 1. Create a GitHub App[​](#1-create-a-github-app "Direct link to 1. Create a GitHub App")

In your GitHub organization or personal account, go to **Settings → Developer settings → GitHub Apps** and create a new app with the following settings:

| Setting                                    | Value                                                             |
| ------------------------------------------ | ----------------------------------------------------------------- |
| **GitHub App name**                        | Your app name (e.g. `Allegro Template Sync`)                      |
| **Homepage URL**                           | Your Allegro instance URL                                         |
| **Webhook URL**                            | `https://your-app.com/github/webhooks`                            |
| **Webhook secret**                         | A random secret string (set as `GITHUB_WEBHOOK_SECRET` in `.env`) |
| **Post installation → Setup URL**          | `https://your-app.com/github/callback`                            |
| **Post installation → Redirect on update** | ✅ Enabled                                                        |

**Permissions required:**

* Repository contents: Read-only

**Subscribe to events:**

* Push
* Installation

### 2. Configure Environment Variables[​](#2-configure-environment-variables "Direct link to 2. Configure Environment Variables")

After creating the GitHub App, add these values to your `.env`:

```dotenv
# GitHub App credentials
GITHUB_APP_ID=<your_app_id>
GITHUB_APP_PRIVATE_KEY="<your_pem_private_key>"
GITHUB_WEBHOOK_SECRET=<your_webhook_secret>

# The installation URL shown on the GitHub Sync settings page
# Format: https://github.com/apps/<app-slug>/installations/new
GITHUB_APP_URL=https://github.com/apps/your-app-name/installations/new

```

note

`GITHUB_APP_PRIVATE_KEY` should be the full PEM content of the private key generated in your GitHub App settings.

***

## Installation Flow[​](#installation-flow "Direct link to Installation Flow")

When an admin visits **Organization Settings → GitHub Sync** and clicks **Connect GitHub Repository**:

1. They are sent to `GITHUB_APP_URL?state={encrypted_tenant_id}` on GitHub.
2. They install the app on their GitHub account/organization.
3. GitHub fires a `installation.created` webhook to `/github/webhooks`, which creates a `GitHubAppInstallation` record on the landlord database.
4. GitHub redirects the user back to `/github/callback?installation_id=XXX&state={encrypted_tenant_id}`.
5. The callback decrypts the state to identify the tenant and links the `GitHubAppInstallation` record to that tenant.
6. The admin is redirected to the GitHub Sync settings page where they enter the repository name and default branch.
7. Upon submitting the form, the tenant is linked and an initial sync is queued.

important

The `Setup URL` in your GitHub App settings **must** be set to `https://your-app.com/github/callback`. Without this, the installation cannot be linked to the tenant.

***

## Sync Process[​](#sync-process "Direct link to Sync Process")

Template sync is handled by the `SyncGitHubTemplates` job. It:

* Fetches all `.json` template files from the repository at the configured branch.
* Creates or updates corresponding `Template` records (matched by `sync_source`).
* Marks templates not present in the repository as deleted.

Syncs are triggered:

* **Automatically** when a push arrives on the configured default branch (via webhook).
* **Manually** via the **Sync Now** button on the GitHub Sync settings page (rate-limited to once every 5 minutes).

***

## Disconnecting[​](#disconnecting "Direct link to Disconnecting")

Admins can disconnect GitHub sync from **Organization Settings → GitHub Sync → Disconnect**. This:

* Soft-deletes the `GitHubAppInstallation` record.
* Clears GitHub fields on the tenant.
* Removes the `sync_source` from all templates, making them editable again.

Templates are **not deleted** when disconnecting.

***

## Database Schema[​](#database-schema "Direct link to Database Schema")

### `github_app_installations` (landlord database)[​](#github_app_installations-landlord-database "Direct link to github_app_installations-landlord-database")

| Column             | Type                   | Description                            |
| ------------------ | ---------------------- | -------------------------------------- |
| `installation_id`  | `bigint` (unique)      | GitHub's installation ID               |
| `tenant_id`        | `bigint` (nullable)    | The linked Allegro tenant              |
| `account_login`    | `string` (nullable)    | GitHub account/org login name          |
| `repository`       | `string` (nullable)    | Full repository name (e.g. `org/repo`) |
| `default_branch`   | `string` (nullable)    | Branch to sync from                    |
| `last_sync_at`     | `timestamp` (nullable) | Time of last successful sync           |
| `last_sync_hash`   | `string` (nullable)    | Commit SHA of last sync                |
| `last_sync_errors` | `json` (nullable)      | Errors from the last sync attempt      |