1. Create the stack and set the sync
Create the stack as usual, then point it at a repository:--apply, --prune and --deploy. stack sync set merges with the current settings: flags you leave out keep their value, --clear-credential drops the credential, and a new sync needs --repo, --branch and --path. The command refuses --prune or --deploy without --apply, and it prints a reminder for every one that is off. Check the result any time:
--json. The REST calls behind them are GET and PUT /api/v1/stacks/{name}/sync, where apply, prune and deploy must each be sent as true or false.
2. Rotate the webhook secret
secret, and the absolute sync_url and refresh_url built from the dashboard URL setting (the request’s own host when none is set), (with --json as an object with those three keys) and warns on stderr that the secret is not shown again. It is stored sealed and no GET returns it; levelrail stack sync status infra only says whether one is set. Rotating again replaces it. Deleting the stack removes it; turning the sync off keeps it, and deliveries signed with the old one stop working. Root or a stack admin can rotate, and each rotation is in the audit log.
3. Add the webhook
Two URLs exist per stack:
GitHub: repository Settings, Webhooks, Add webhook. Payload URL is one of the URLs above, content type
application/json, secret is the rotated secret, events: just the push event. GitHub signs each delivery with X-Hub-Signature-256; a delivery signed only with the older SHA-1 header is refused.
GitLab: project Settings, Webhooks. URL is one of the URLs above, secret token is the rotated secret, trigger: push events. GitLab sends the token in X-Gitlab-Token.
What the webhook answers
The webhook answers at once and never waits for the fetch. Only the ref and the head commit are read from the payload. Repeated deliveries are harmless: a stack never runs two syncs at once, and a burst becomes at most one running and one pending sync. Each trigger emits a
stacks.sync_triggered event with the verb, branch, short commit and provider, never the payload.
Safety checks on every sync
- A document that holds a plaintext secret is refused with
sync_secret_in_repo. Reference secrets instead of writing them into git. - A fetch is refused with
sync_disk_lowwhile free disk is belowstacks.sync_min_free_mb. - Repository size, file count and file size are capped by the
stacks.sync_*runtime settings.
levelrail stack sync status <stack> for the latest commit, plan hash and counts.