# Push-to-deploy and deploy hooks

> Deploy automatically on every git push, or trigger deployments from CI and chat with Falak deploy hook URLs, including branch, commit and custom variables.

Source: https://falak.sh/docs/guides/push-to-deploy/

Falak can start a deployment in five ways: the **Deploy** button, the API or CLI, a **push** to the site's branch, a **deploy hook** URL, or a rollback. This page covers the two automatic ones.

![Deploy settings: strategy choices (zero downtime, in place, rolling, canary), releases to keep, health check settings, the push-to-deploy toggle and the deploy hook URL.](./_images/sites-site-deploy-settings.png)

## Push-to-deploy

When push-to-deploy is on, every push to the site's branch deploys the pushed commit.

1. Connect the repository through a Git connection (GitHub App, token, or custom git with a webhook).
2. Open the site's **Settings → Source** and turn on **Push to deploy**. Sites created from the canvas have it on already; sites created through the API default to off (`push_to_deploy: false`).
3. Push to the branch.

How the webhook reaches Falak depends on the connection:

| Connection | Webhook |
|---|---|
| GitHub App | The app's single webhook; nothing to set up |
| GitHub / GitLab / Bitbucket token | Falak creates a webhook on the repository through the provider's API |
| Custom git | You add the webhook on your git server; see [Custom git webhooks](/docs/guides/connect-git-tokens/#webhooks-for-custom-git-servers) |

Only branch pushes count; tag pushes and branch deletions are ignored. **Settings → Source control → Recent pushes** shows the last 20 deliveries.

Your panel must be reachable from your git provider. If it is only reachable under another name, set `FALAK_WEBHOOK_URL` to that public base URL.

## Deploy hooks

A deploy hook is a secret URL that starts a deployment when requested. Use it from CI, cron, chat bots, or git servers without webhooks.

1. Open the site's **Settings → Deploy** (Deploy hook) and click **Create URL**.
2. Copy the URL. It looks like `https://falak.example.com/api/deploy/<token>`.
3. Call it with `GET` or `POST`.

```bash title="Deploy the site's branch head"
curl -fsS -X POST "https://falak.example.com/api/deploy/$FALAK_HOOK_TOKEN"
```

```json title="Response (202)"
{"data": {"id": "01k…", "status": "building", "number": 42, "url": "https://falak.example.com/sites/01k…/deployments/01k…"}}
```

### Parameters

| Query parameter | Meaning |
|---|---|
| `falak_deploy_branch` | Branch to deploy (default: the site's branch) |
| `falak_deploy_commit` | Exact commit SHA (7–64 hex characters) |
| `falak_deploy_author` | Author shown in the UI and exported as `FALAK_COMMIT_AUTHOR` |
| `falak_deploy_message` | Message shown in the UI and exported as `FALAK_COMMIT_MESSAGE` |
| anything else | Exported as `FALAK_VAR_` to the deploy script (upper-cased, non-alphanumerics become `_`); at most 50 variables of 4 KiB each, stored encrypted |

```bash title="Deploy an exact commit from CI with context"
curl -fsS -X POST "https://falak.example.com/api/deploy/$FALAK_HOOK_TOKEN?falak_deploy_commit=$GITHUB_SHA&falak_deploy_author=$GITHUB_ACTOR&release_notes=yes"
# the deploy script sees FALAK_VAR_RELEASE_NOTES=yes
```

| Status | Meaning |
|---|---|
| `202` | Deployment created (or merged into a waiting one) |
| `404` | Unknown or rotated token |
| `422` | Invalid commit |
| `429` | More than 30 calls per minute |

Regenerating the URL invalidates the old one. Treat the URL like a password.

## Which to use from CI

| Need | Use |
|---|---|
| Fire and forget | Deploy hook |
| Wait for the result and fail the CI job | `falak deploy <site> --wait` (exit code 3 on failure). See [CLI in CI](/docs/cli/ci/). |
| Full control, JSON | `POST /api/v1/sites/{site}/deployments` and poll. See [Deployments API](/docs/api/deployments/). |

## Next steps