GantryCD
Connecting repositories
A stack always points at a repository. By default GantryCD just reads it as a public repo. Connecting an SCM integration unlocks two things: access to private repositories, and automatic deployments driven by repository activity.
SCM integrations
An SCM integration is an organization-scoped connection to a Git provider — today, a GitHub App. You create it under Org settings → SCM integrations.
An integration matches repositories by a regex pattern and a priority. When GantryCD needs to act on a repository URL, it walks the org’s integrations in priority order and the first matching pattern wins. A URL that matches nothing is treated as a public repository. This lets one org route different repos through different GitHub Apps.
A GitHub App integration gives GantryCD two capabilities:
- Cloning private repos — at run time GantryCD mints a short-lived installation token so the runner can clone the exact commit.
- Receiving webhooks — so pushes and PRs become deployments without polling.
Turning on automatic deployments
Each integration has its own webhook endpoint. After creating the integration,
copy the webhook URL and secret shown on its page into the GitHub App’s
webhook settings, and subscribe the App to the push and pull_request events.
(Stacks that use promotion gates
need two more events — see the GitHub App page.)
Note: The webhook URL only appears when the backend knows its public address — set
GANTRYCD_BACKEND_PUBLIC_BASE_URL. See Configuration.
Once delivery is wired up, repository activity drives two deliberately different outcomes:
| Activity | What GantryCD does |
|---|---|
| Push to a stack’s tracked branch | Updates the commit and creates a normal plan deployment for each stack whose project root the push actually changed — the deployment you see in the stack’s deployments view. |
| Pull request opened/updated | Creates a preview plan scoped to the PR. It never takes the stack lock and stays in the pull-requests view. |
A push only triggers the stacks whose project root contains a changed file, so
in a monorepo a change under one directory won’t re-plan unrelated stacks (a
stack rooted at / owns the whole repo and always runs). A push to a branch that
no stack tracks is a cheap no-op. Pull request previews are covered in
Pull requests.
Syncing without webhooks
You don’t need webhooks to deploy. Syncing a stack asks the matching integration (or the public repo) for the latest commit on the tracked branch and records it. A stack must be synced at least once before you can deploy it. You can sync from the UI, the CLI, or let webhooks do it for you on every push.
How delivery stays reliable
Webhook handling is built to never drop a delivery:
- The endpoint verifies the signature, normalizes the event, and writes it to a durable inbox — it never filters against your stacks at the door, so a delivery is always retryable.
- A background worker processes the inbox, so a slow GitHub API call never holds up a delivery.
- Duplicate deliveries (GitHub retries) are absorbed by the delivery id.
You don’t operate any of this; it’s here so you know an event won’t be silently lost. Implementation detail lives in SCM And Pull Requests.