Git Integration

Connect GitHub, GitLab, Bitbucket, or a custom Git server once, then reuse the connection across every site you deploy. Push code, auto-deploy fires — no CI pipeline required.

Overview

Deploynix separates Git integration into two layers: Git Providers (the accounts — your GitHub org, your GitLab group) and Git Repositories (specific repos you've wired into Deploynix for deployment). You connect a provider once; after that, adding a repository becomes picking it from a list, and every site that uses the repo shares the same deploy key and webhook. When a push arrives, Deploynix verifies the signature, matches the pushed branch against every site using that repo, and deploys the ones whose branch matches.

Providers vs. Repositories

Understanding the two-layer model up front makes everything on this page click.

• Git Provider — an authenticated connection to an entire Git account: your GitHub user or org, your GitLab group, etc. Connect one under Settings → Git Providers. Credentials (OAuth tokens, personal access tokens) are stored encrypted and scoped to your organization.
• Git Repository — a specific repo you've wired into Deploynix for deployment. Lives under Settings → Git Repositories. Each repo has its own ED25519 deploy key, its own webhook secret, and an auto-deploy toggle. Any number of sites can attach to the same repository, each with a different branch.

Connecting a Git Provider

You can connect over OAuth (recommended — it enables automatic deploy-key and webhook setup) or with a personal access token.

OAuth

1. Open Settings → Git Providers.
2. Click Connect next to your provider.
3. You're redirected to the provider's OAuth consent screen. Authorize Deploynix.
4. You land back in the dashboard with the connection listed. Access and refresh tokens are stored encrypted.

Personal Access Token

If your organization prefers token-based auth, generate a PAT on the provider with the scopes below and paste it into Add Git Provider → Personal Access Token. Tokens are validated against the provider's API before being stored encrypted.

Provider-Specific Setup

GitHub

• OAuth — one-click via GitHub's consent screen.
• PAT — Settings → Developer settings → Personal access tokens. Required scopes: repo, admin:repo_hook.
• Deploy key — Repo Settings → Deploy keys → Add deploy key.

GitLab (Cloud & Self-Hosted)

• OAuth — supports gitlab.com and self-hosted instances; you can specify the base URL at connection time.
• PAT — User Settings → Access tokens. Required scopes: api, read_repository, write_repository.
• Deploy key — Project Settings → Repository → Deploy Keys.

Bitbucket

• OAuth — one-click via Bitbucket's consent screen.
• App password — Personal settings → App passwords. Required permissions: repository, repository:admin, webhook.
• Deploy key — Repository Settings → Access keys.

Custom Git (Gitea, Self-Hosted, etc.)

• No OAuth — provide the repository URL (SSH or HTTPS) and an optional token.
• Deploy keys and webhooks are not auto-installed — Deploynix will display the generated public key and webhook URL so you can install both manually in your Git server.

For the exact scopes and step-by-step token creation instructions per provider, see the Provider Permissions reference.

Adding a Repository

1. Open Settings → Git Repositories and click Add Repository.
2. Pick a connected provider (or paste a clone URL for a public repository).
3. Choose the repository from the list — or enter its owner/name manually for custom providers.
4. Pick a default branch. Individual sites can override this later.
5. Click Save. Deploynix generates an ED25519 deploy keypair and a webhook secret for the repository.
6. For OAuth providers, Deploynix installs the deploy key and webhook via the provider's API automatically. For custom providers, copy both from the repository's card and install them yourself.

Deploy Keys

Each repository in Deploynix gets its own ED25519 deploy keypair. The private key is encrypted at rest and used by every managed server that deploys a site attached to the repo; the public key is shown in the repository card so you can install it anywhere Deploynix can't reach on its own.

Webhooks

Each repository has a unique webhook URL of the form:

https://{your-deploynix-domain}/webhooks/git-repository/{repository-uuid}

Deploynix verifies every request against the repository's encrypted webhook secret before processing it:

• GitHub — HMAC-SHA256 via the X-Hub-Signature-256 header.
• GitLab — shared-secret comparison via X-Gitlab-Token.
• Bitbucket — HMAC-SHA256 via X-Hub-Signature.

For OAuth providers, Deploynix registers the webhook automatically when you add the repository. For custom providers, install it yourself: set the URL shown in the repository card, content type application/json, and subscribe to push events only.

Auto-Deploy

Auto-deploy is a flag on the Git Repository, not on individual sites. Enable it once and every push to a site's branch triggers a deploy for that site.

1. Open Settings → Git Repositories.
2. Find the repository and toggle Auto Deploy on.
3. Push to any site's configured branch — the deploy fires automatically.

Branch Matching

Matching is a strict string comparison against each site's configured branch. The flow for every incoming webhook:

1. Verify the signature — reject mismatches.
2. Parse the event and the pushed branch. GitHub and GitLab strip refs/heads/ from the ref; Bitbucket reads push.changes[0].new.name.
3. For every site attached to the repository, check if the site's branch equals the pushed branch.
4. For matches: create a webhook record with status received and queue the deploy.
5. For non-matches: create a webhook record with status skipped so you can see the push came in but was intentionally ignored.

Webhook History

Every webhook delivery is recorded on the site as a SiteWebhook row. Each record captures:

• Event — usually push.
• Branch — the pushed branch.
• Commit hash — the SHA that triggered it.
• Commit message — truncated to the first 500 characters.
• Pusher — the user who pushed.
• Status — received, deploying, deployed, failed, or skipped.
• Payload — encrypted at rest with sensitive keys filtered out.

That's your audit trail: at any point you can see exactly which pushes triggered which deploys, and which were skipped because the branch didn't match.

One Repository, Many Sites

One repository can power any number of sites, each with its own branch and environment — the canonical use case is staging and production on the same codebase:

• Create a staging site on the develop branch with staging env variables.
• Create a production site on the main branch with production env variables.
• Both sites share the same repository, the same deploy key, and the same webhook — a push to develop deploys staging, a push to main deploys production, and pushes to any other branch are recorded as skipped on both sites.

Public Repositories Without a Provider

If you just want to deploy a public repository, you can paste its HTTPS clone URL when adding a repository without connecting a provider first. Cloning works straight away because no auth is required. The trade-off is no API access, which means:

• You install the webhook manually in your Git host if you want auto-deploy.
• No deploy key is needed — the repo is public.
• Signature verification still runs against the webhook secret Deploynix generates for the repository.

Disconnecting & Deleting

Delete a repository from Settings → Git Repositories. Deploynix refuses to delete a repository that still has sites attached — detach or delete the sites first.

Disconnect a provider from Settings → Git Providers. Repositories previously connected through that provider remain in Deploynix — existing deploy keys keep working, and you can still deploy — but automatic deploy-key and webhook installation will no longer work for new repositories until you reconnect.

Security

• OAuth tokens, personal access tokens, and deploy-key private keys are encrypted at rest using Laravel's APP_KEY.
• Webhook secrets are encrypted and never shown in API responses; only the webhook URL is visible in the UI.
• Webhook payloads are verified by signature before any deploy work starts — an unsigned or mis-signed request is rejected outright and never reaches the job queue.
• Deploy keys are read-only by convention — leave "Allow write access" unchecked on every provider.

Troubleshooting

A push didn't trigger a deploy

• Check the webhook history on the site — if the row is marked skipped, the pushed branch didn't match the site's branch.
• Confirm Auto Deploy is on for the repository.
• Check the webhook delivery log in your Git provider — a failed delivery there means Deploynix never received the push.
• If you rotated the webhook secret, reinstall the webhook in the provider so the new secret takes effect.

Clone failed during deploy

• Confirm the deploy key is installed on the repository and has read access.
• For OAuth connections, re-run Setup Deploy Key from the repository card — it retries the provider API call.
• For PAT / custom providers, double-check the URL format and that the token still has the required scopes.

Signature verification failed

• You have stale webhook settings. Open the repository in Deploynix, copy the current webhook URL and secret, and replace the webhook in the Git provider.
• Ensure the webhook content type is application/json, not application/x-www-form-urlencoded.