Auto-deploy on push

Once your app is deployed, you don't want to press Deploy every time you change something. Auto-deploy does it for you: you push to the project's branch as usual, the Git host tells Synq about the push through a webhook (a small HTTP message sent the moment you push), and Synq builds and ships that commit.

Which setup applies

In every case the push has to reach Synq over the internet: the panel needs a public address: SYNQ_PUBLIC_URL (for example https://panel.example.com, set by the installer's --domain or by synq panel-domain), or a verified, SSL-ready primary domain on the Synq app itself. The GitHub setup has a way around that (a verified project domain); the others do not.

GitHub

How the GitHub webhook is wired

Synq picks the simplest route that works:

• Public Synq: turning on Auto Deploy registers a webhook on the repository that points at <public URL>/api/proxy/api/webhooks/github, for example https://app.example.com/api/proxy/api/webhooks/github. Each project gets its own webhook secret, and every delivery's X-Hub-Signature-256 signature is checked against it.
• Verified domain: with a Webhook Endpoint set, GitHub delivers to https://<your-domain>/_synq/hooks/github, which the edge passes to Synq. This is the option for private installs.
• Your own GitHub App: with a self-hosted GitHub App, push events arrive through the App; there is no separate per-repository webhook to manage.

Creating the repository webhook needs admin access to the repository through your GitHub connection.

Which GitHub pushes deploy

• Only pushes to the project's deploy branch deploy. Pushes to other branches are ignored (preview environments, if you use them, track their own branches; see Preview environments).
• For a Compose or monorepo project, Synq reads which files changed and rebuilds only the services they affect. A push that touches none of them is skipped.
• A commit that is already building or live is not deployed twice, and a redelivered webhook is recognized.

From the CLI

You need the project's ID (synq project list).

# Turn auto-deploy on, or off again
synq project git auto-deploy <project-id> --enable
synq project git auto-deploy <project-id> --disable

# Deliver webhooks to a verified project domain (for private instances), or stop
synq project git webhook-domain <project-id> deploy.yourapp.com
synq project git webhook-domain <project-id> --clear

# Change the deploy branch
synq project git branch <project-id> main

GitLab, Bitbucket, Gitea and Forgejo

A project imported from the Git URL tab (see Deploy from any Git URL) has its own webhook URL and secret. You turn auto-deploy on in Synq, then add that webhook in your Git provider once.

GitLab

1. In GitLab, open the project, then Settings → Webhooks → Add new webhook.
2. Paste the Webhook URL into URL.
3. Paste the Secret into Secret token.
4. Under Trigger, select Push events (you can filter to your deploy branch), then Add webhook.

GitLab sends the secret as the X-Gitlab-Token header. Works for gitlab.com and self-managed GitLab.

Gitea

1. In Gitea, open the repository, then Settings → Webhooks → Add webhook → Gitea.
2. Paste the Webhook URL into Target URL and keep POST with application/json.
3. Paste the Secret into Secret.
4. Choose Push events, set Branch filter to your deploy branch, then Add webhook.

Forgejo and Codeberg

1. In Forgejo, open the repository, then Settings → Webhooks → Add webhook → Forgejo.
2. Paste the Webhook URL into Target URL and keep POST with application/json.
3. Paste the Secret into Secret.
4. Choose Push events, set Branch filter to your deploy branch, then Add webhook.

Bitbucket

1. In Bitbucket, open the repository, then Repository settings → Webhooks → Add webhook.
2. Enter a title and paste the Webhook URL into URL.
3. Paste the Secret into Secret.
4. Under Triggers, keep Repository push, then Save. Pushes to other branches are ignored.

Bitbucket Cloud (repo:push) and Bitbucket Data Center (repo:refs_changed) are both understood.

GitHub repositories imported by Git URL

If you imported a GitHub repository through the Git URL tab, add a repository webhook on GitHub yourself: Settings → Webhooks → Add webhook, Payload URL set to the Webhook URL, Content type application/json, Secret set to the Secret, and Just the push event.

Git servers without webhooks

A plain Git server (for example one reached only over SSH) has no webhook settings. Create a deploy hook and call it from the repository's post-receive hook, for example curl -fsS -X POST -H "Authorization: Bearer <token>" <delivery URL>.

How deliveries are verified

The secret proves a delivery is for this project. Each provider sends it differently:

A delivery with none of these, or with an old SHA-1 signature, is refused with 401. The body must be JSON (content type application/json).

Which pushes deploy

• Only a push to the project's Branch deploys. When the branch field is empty, the repository's default branch counts. A deleted branch never deploys.
• A provider's ping or test event is answered and logged as ignored. Other events (tags, merge requests, issues) are ignored too.
• With Auto-deploy on push off, a push is logged as skipped ("Auto-deploy on push is off for this project.").
• A commit that is already deployed or deploying is skipped, so redeliveries are harmless.
• For a Compose or monorepo project, GitLab, Gitea and Forgejo include the changed files, so only the affected services rebuild. Bitbucket does not send file lists, and neither does any provider for a force push or a push of 20 commits or more: then every service rebuilds.
• The deploy runs as the organization's owner, since no person pressed the button.

Rotate the secret

Press Rotate secret on the Deploy on push card. Deliveries fail with 401 until you paste the new secret into the provider's webhook settings, so do both at once.

Delivery log

Every push delivery and deploy hook call is logged per project:

• For Git URL projects, Recent deliveries sits under the Deploy on push card ("No deliveries yet. Use your provider's test button to send one." until the first arrives).
• For every project, Source & Triggers → Webhooks shows the same feed under Recent deliveries ("GitHub pushes and custom hook calls received for this project.").

Each row shows the outcome (dispatched, skipped, ignored, failed), the branch and short commit for a push, when it arrived, and the error for a failed delivery. Load more loads older rows.

Troubleshooting

Related