Docs / API & Webhooks / Git Webhook Setup Patterns

Git Webhook Setup Patterns

Published · Last updated: May 2026 · 3 min read

Who this is for

Developers who want automatic deployments triggered by git push events (push to main branch deploys automatically).

What you will complete

Connect your git repository to a CloudAIPilot site or app so that pushes to specific branches trigger deployments automatically.

Before you begin

  • A GitHub, GitLab, or Bitbucket account connected to CloudAIPilot (see KB-04-05 for apps, KB-03-08 for sites).
  • A site or app with a git repository linked.

How git webhooks work in CloudAIPilot

When you link a git repository to a site or app, CloudAIPilot registers a webhook with your git provider. The git provider sends a POST request to CloudAIPilot when a push event occurs. CloudAIPilot receives the push event, checks which branch was pushed to, and triggers a deployment if it matches the configured deploy branch.

The flow:

  1. You push code to your repository.
  2. The git provider (GitHub, GitLab, Bitbucket) sends a webhook to CloudAIPilot.
  3. CloudAIPilot checks: does this push match the deploy branch for any linked site or app?
  4. If yes: a new deployment starts automatically.
  5. The deployment appears in the site or app's deployment history and the Activity Center.

Step-by-step: link a git repository for auto-deploy (Sites)

  1. Go to the site's detail page and click the Git Settings tab.
  2. Click Connect Repository.
  3. Select your git provider (GitHub, GitLab, Bitbucket).
  4. Authorize CloudAIPilot to access your repositories if prompted.
  5. Select the repository from the list.
  6. Set the Deploy Branch — the branch that triggers deployments (typically main or master for production, develop for staging).
  7. Click Save.
  8. CloudAIPilot registers a webhook with your git provider automatically.
  9. To verify: push a test commit to the deploy branch and check the deployment history.

Step-by-step: link a git repository for auto-deploy (Apps)

  1. Go to the app's detail page.
  2. Click Repository Linking or the Git settings option.
  3. Select your provider, repository, and deploy branch.
  4. Save. CloudAIPilot registers the webhook.

See KB-04-04 and KB-04-06 for more detail on app-specific git deploy configuration.

Branch-based deployment patterns

Single branch (simple): One repository, deploy branch = main. Every push to main deploys to production. Simple but risky — a bad push goes straight to production.

Branch-per-environment: Link the same repository to two sites: one staging site with deploy branch develop, one production site with deploy branch main. Pushes to develop deploy to staging. Merges to main deploy to production. Recommended for most teams.

Manual deploys with webhook trigger: Link the repository but trigger deployments manually (via dashboard or the commit picker) rather than automatically on every push. Good for teams that want to control exactly when a deployment happens.

Troubleshooting webhook triggers

"I pushed to the deploy branch but no deployment started" Check 1: Go to Settings → Git Integration and verify the repository is still connected and the webhook is registered. Check 2: Check the repository's webhook settings directly in GitHub/GitLab/Bitbucket — verify the CloudAIPilot webhook URL is listed and not showing delivery errors. Check 3: See KB-12-11 for the full webhook debugging playbook.

"Deployments trigger on every branch push, not just the deploy branch" Cause: The deploy branch filter may not be configured or the webhook was set up to trigger on all push events. Fix: Check the deploy branch setting on the site or app's git settings. Set it to the specific branch only.

Related articles