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

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

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

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

# 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

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

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

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

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