# Deploy on git push: branches, watch paths and waiting for CI.

Deploy on git push for the configured branch, only after Watch paths match a change in that app and GitHub checks have passed.

Canonical URL: https://unbroker.cloud/blog/deploy-on-git-push
Published: 2026-11-04
Reviewed: 2026-11-04
Author: Timoteo Borgobello

## The short answer

Deploy on git push is three decisions: which branch deploys, what counts as a change to that app, and what has to pass first. A push should queue a deployment only when something in that app changed and the GitHub checks already passed.

Those settings live on a GitHub-connected service. [Deploy from Git](https://docs.unbroker.cloud/deployments/git) is the reference. The October 5 and October 21 notes are [Wait for CI](https://unbroker.cloud/changelog/2026-10-05-wait-for-ci) and [Watch paths](https://unbroker.cloud/changelog/2026-10-21-watch-paths).

## How a push deployment works

Connect a repository when you create the service. Unbroker keeps the repository, branch, and triggering commit on every deployment.

For a GitHub-connected service with automatic deploys enabled, a push to its configured branch queues a deployment. The Unbroker GitHub connection is what receives that push. That is the auto deploy from GitHub. To deploy a GitHub repo on push, automatic deploys have to be on, and the push has to be that branch. Manual deploys remain available from the console and the CLI.

The deployment then moves through queued, building, deploying, and live. A failed health check is not treated as live. The map is the [deployments overview](https://docs.unbroker.cloud/deployments/overview). The CLI walkthrough is [Deploy an app from Git](https://docs.unbroker.cloud/guides/deploy-from-git).

## Pick the branch that deploys

The branch you configure is the one a push deploys. Point the production service at the branch you release.

Other branches go to a pull request preview when that feature is on. Previews require Pro. When they are enabled on a production service, opening or updating a pull request creates or updates the preview and deploys the pull request head. GitHub delivers those events through the repository connection. Previews inherit the service's Wait for CI setting. How to keep a preview off production data is in [Pull request preview environments](https://unbroker.cloud/blog/pull-request-preview-environments).

A Node service starts from [Deploy Node.js](https://unbroker.cloud/deploy/nodejs). A Next.js app starts from [Deploy Next.js](https://unbroker.cloud/deploy/nextjs).

## Watch paths in a monorepo

Watch paths are how a monorepo deploys only the app that changed. Set them when you create a repository service, under Build & deploy, or later in Source. Enter one pattern per line, relative to the repository root, even when Root directory is set. A Watch paths deploy runs when a matching file is added, modified, or removed.

```text
apps/web/**
packages/sdk/**
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
.dockerignore
```

`*` matches zero or more characters inside one path segment. `?` matches one character. A whole `**` segment matches zero or more path segments, as in `apps/**/Dockerfile`. Hidden files are included. Exclusions are not supported, so the list cannot drop a path. Include shared packages, lockfiles, and Dockerfiles that affect the build. The example above is the one in the Git docs: `apps/web`, `packages/sdk`, the lockfiles, and `.dockerignore`.

Configured patterns replace the root-directory push filter. They do not change the build context. An empty list keeps the existing behavior: watch the root directory when one is set, otherwise the whole repository. The API field is `watchPaths`. Send `[]` to clear it. The change applies to later pushes and does not redeploy the service by itself.

Filtering happens before Wait for CI. Manual deploys, deploy hooks, and pull request previews are unaffected. If the repository is a Compose file instead of one directory per app, the map from that file to services is [Docker Compose in production](https://unbroker.cloud/blog/docker-compose-to-production).

## When a filtered service still deploys

Path filtering trusts the file list GitHub sends. If that list is incomplete, the push is a force push, or a large push exceeds the webhook's matching-work budget, Unbroker deploys conservatively. A commit whose file list is complete and empty does not trigger a path-filtered service.

## Wait for CI

Wait for CI is the switch to deploy only after CI passes. Turn it on in the service settings and a push does not deploy immediately. Unbroker waits until every GitHub check on the commit has finished, then deploys if they all passed. That is how you wait for GitHub checks before deploy.

GitHub describes two kinds of status checks: checks created by GitHub Apps, including GitHub Actions, and commit statuses created by external services. The Unbroker setting follows GitHub checks on that commit. It is not documented as a filter that accepts only Actions.

Three timings come with the setting:

- A newer push, while a commit is still waiting, replaces that commit.
- A commit that never gets a check is deployed after two minutes.
- If CI never finishes, the commit is dropped after two hours.

Watch paths run first. A push that matches no pattern does not reach the wait. The source note is [Wait for CI before deploying](https://unbroker.cloud/changelog/2026-10-05-wait-for-ci). GitHub's description of the checks themselves is [About status checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks).

## What a live deploy does not prove

Live means the health check passed and traffic can reach that revision. It does not prove every route. After the deployment is live, request an endpoint you expect and read the response. A healthy process does not prove every feature, including a database read or a signed-in path.

A migration is a separate release step. [Database migrations on deploy](https://unbroker.cloud/blog/database-migrations-on-deploy) is that step: it runs once, before the new version is live, and a code rollback does not undo the schema. Migration commands require Pro. A rollback promotes a known deployment and does not rebuild the source commit. It skips the pre-deploy command, and it does not restore a database or a volume, so a migration has to stay safe after that promotion. The rollback sentence is in the [deployments CLI](https://docs.unbroker.cloud/cli/deployments). The pre-deploy and database limits are in [Letting a coding agent deploy safely](https://unbroker.cloud/blog/coding-agent-deploy-safely). Plan rows are in [Plans](https://docs.unbroker.cloud/billing/plans).

## GitLab and Bitbucket

The push rule above is for a GitHub-connected service. GitLab and Bitbucket merge requests use the service's deploy hook. Generic deploy hooks require Pro. Pull request previews require Pro as well. Private repository credentials require Pro.

Pro is a $25 monthly commitment with $25 of usage credit each billing cycle. The credit does not roll over. If eligible usage is under $25, the charge is still $25. Current figures are on [pricing](https://unbroker.cloud/pricing).

## Deploy from the terminal

Creating a service with the CLI needs a Pro organization and an API token. Eligible Free apps can be created in Cloud instead. The documented create command is:

```bash
ubctl apps services create <projectId> \
  --name api \
  --repo https://github.com/acme/api \
  --framework node
```

Follow it with a wait. `--wait` returns a non-zero exit code when the deployment fails:

```bash
ubctl apps deploy <serviceId> --wait
```

A coding agent can run the same commands. What it is allowed to do is on [Deploy with Claude Code](https://unbroker.cloud/deploy/claude-code). What the token must not see, and what a rollback skips, is in [Letting a coding agent deploy safely](https://unbroker.cloud/blog/coding-agent-deploy-safely).

## Checklist

1. Connect the GitHub repository and leave automatic deploys enabled.
2. Set the branch that should deploy. Use a pull request preview, on Pro, for the other branches.
3. In a monorepo, set Watch paths from the repository root. Include the app, shared packages, lockfiles, and the Dockerfile.
4. Leave the list empty only when the root directory, or the whole repository, should deploy.
5. Turn on Wait for CI when a push should wait until every GitHub check has passed.
6. After the deployment is live, request a real endpoint.
7. Treat migrations as their own step. A rollback does not rebuild the commit and does not restore a database.

## FAQ

### Does Unbroker auto-deploy a GitHub repo on every push?

A GitHub-connected service with automatic deploys enabled queues a deployment when a push lands on its configured branch. Other branches do not take that path. Watch paths can limit the queue to matching files. Manual deploys stay available from the console and the CLI. The rule is in Deploy from Git.

### Can a deploy wait until GitHub Actions checks pass?

Wait for CI waits until every GitHub check on the commit has finished, then deploys if they all passed. GitHub Actions is one way those checks are created. The setting is not documented as Actions-only. A newer push replaces the commit that is waiting. If CI never finishes, that commit is dropped after two hours.

### What if the repository has no CI checks?

A commit that never gets a check is deployed after two minutes. The Wait for CI note says this so a repository without CI is not left waiting.

### How do you stop a monorepo from redeploying every app?

Set Watch paths, one pattern per line, relative to the repository root. Include that app, shared packages, lockfiles, and the Dockerfile. An empty list keeps the previous behavior: the root directory when one is set, otherwise the whole repository.

### Do Watch paths affect manual deploys or pull request previews?

No. Manual deploys, deploy hooks, and pull request previews ignore Watch paths. Filtering applies to automatic push deployments, and it runs before Wait for CI.

### Can a service deploy from GitLab or Bitbucket?

GitLab and Bitbucket merge requests use the service's deploy hook. Generic deploy hooks require Pro. The push rule in Deploy from Git is written for a GitHub-connected service.

### Is push-to-deploy available on Free?

The plans table has no row named push-to-deploy. Free includes managed Node.js and 3 deploy requests per UTC day. Unused deploys do not carry forward. Pull request previews, generic deploy hooks, and private repository credentials are not on Free. Pro has no plan request cap.

## Related reading

- [Pull request preview environments](https://unbroker.cloud/blog/pull-request-preview-environments)
- [Letting a coding agent deploy safely](https://unbroker.cloud/blog/coding-agent-deploy-safely)
- [Docker Compose in production](https://unbroker.cloud/blog/docker-compose-to-production)
- [Deploy Node.js](https://unbroker.cloud/deploy/nodejs)
- [Deploy Next.js](https://unbroker.cloud/deploy/nextjs)
- [Pricing](https://unbroker.cloud/pricing)
