Repositories

A stack points to a repository URL, branch, and working directory. Public repositories work without an integration. Add one for private repositories, push events, and pull requests.

GantryCD supports source control through provider integrations. GitHub is available today.

GitHub

GantryCD connects to GitHub through a GitHub App. The App provides short-lived repository access and sends signed events to GantryCD.

Create the GitHub App

In GitHub, open Settings → Developer settings → GitHub Apps and create a GitHub App. Use your GantryCD address as the homepage. GantryCD does not need a callback URL or user authorization. You can leave the webhook inactive until the App has been added to GantryCD.

Set these repository permissions:

Permission	Access	When needed
Metadata	Read	Always. GitHub adds this permission.
Contents	Read	Clone code, read commits, and handle pushes.
Pull requests	Read	Create pull request previews and read approvals.
Checks	Read	Only for required CI checks.
Commit statuses	Read, or read and write	Read for required legacy checks. Read and write to publish deployment status.
Deployments	Read and write	To publish GantryCD deployment status.

Subscribe the App to these events:

Push and Pull request for the normal setup.
Pull request review and Check suite when stacks have required approvals or CI checks.

Create the App, note its App ID, and generate a private key. Install the App only on the repositories GantryCD should access.

Add the App to GantryCD

Open Settings → Source Control Management → Add Integration and enter:

Name: a name for this integration.
App ID: the ID shown in the GitHub App settings.
Private Key: the full contents of the generated .pem file.
Webhook Secret: a random value that you will also set in GitHub.
Repository Pattern: all GitHub repositories, or a regular expression for the repository URLs this App should handle.
Priority: which integration wins when more than one pattern matches. A lower number wins.

The private key and webhook secret cannot be read back after they are saved.

Connect the webhook

After creating the integration, open it and copy its Webhook URL. Return to the GitHub App settings and:

Enable the webhook.
Paste the GantryCD URL into Webhook URL.
Set the content type to application/json.
Enter the same webhook secret used in GantryCD.
Select the events listed above.

After changing App permissions, approve the request on the GitHub App installation.

Use the repository

Enter the GitHub repository URL on the stack. A push to its tracked branch creates a normal plan. Pull request events create or update a preview plan.

Use manual sync after changing repository settings or when an event was missed. Sync records the current commit without creating a deployment.