Projects and services
Source and deploy triggers
Change a service's branch or repository, choose when pushes deploy, and watch paths in a monorepo.
Updated
A service built from GitHub follows one branch of one repository, and deploys when that branch receives a push. All three are set on the Source card of the service's Overview section, beside the build settings, and saved with Save source.
Change the branch or repository
The card's Account, Repository and Branch fields work as they do on the create form. Pick another branch, another repository, or another connected GitHub account, then press Save source.
Choosing a new repository or branch makes Cloud read it and fill Build with, the commands and Publish directory from what it finds, over what the fields held. Check them before you save.
The account must be one you connected under Settings, Git providers. Cloud refuses any other with "Choose the GitHub installation that can read the repository."
The change is Cloud's own record. What is running keeps running, and the next deployment clones the new branch.
Pushes follow the new branch as soon as you save: from then on a push to the old branch deploys nothing.
A service built from GitHub stays built from GitHub. To run an image instead, create another service.
Deploy on
Deploy on decides what starts a deployment:
| Deploy on | What happens |
|---|---|
| Every push | The default. A push to the branch deploys the service, subject to its watch paths. |
| Only when I ask | Pushes are ignored. The service deploys only when you press Deploy. |
Choose Only when I ask for a service you want to release on your own schedule, or one that shares a repository with services you deploy more often.
Watch paths
Watch paths narrow Every push to the pushes that touched part of the repository. The field is available only while Deploy on is Every push.
Write one directory on each line, from the repository's root.
apps/web,/apps/weband/apps/web/are the same path.A push deploys when any file it added, changed or removed sits inside one of the watched directories.
Empty watches the whole repository.
Up to 20 paths, each at most 255 characters. A blank line is dropped. A path with
..in it, or more than 20 of them, is refused with "Watch a directory in the repository, such as /apps/web, at most 20 of them."
Large pushes deploy regardless
GitHub lists at most 20 commits in the notification it sends for a push, and does not say what the rest touched. A push of 20 commits or more therefore deploys whatever it changed: Cloud treats an extra build as cheaper than a release that silently never ships.
A monorepo, service by service
One repository can feed several services, each with its own build path and watch paths:
apps
- web
- api
packages
- ui
| Service | Build path | Watch paths |
|---|---|---|
web | apps/web | apps/web and packages/ui |
api | apps/api | apps/api |
A push that changes only apps/api deploys api and leaves web alone. Watch the shared directories an application builds from as well as its own, as web watches packages/ui here: a change the watch paths do not cover deploys nothing, even when the application uses it.
Pushes that do not deploy
A push deploys nothing when:
it is to another branch, it pushes a tag, or it deletes the branch;
Deploy on is Only when I ask;
the service has watch paths and the push touched none of them;
a deployment of the service is still running;
your account is suspended;
the service has backup work that has not finished, or a volume attachment that is not confirmed.
In the last three cases the push is dropped, not queued: the commit it carried is deployed only by a later push or by pressing Deploy. A push did not deploy walks through each case.
Which commit a deploy builds
A deployment builds the head of the branch at the moment Cloud hands it to the build, which can be a later commit than the push that started it. The deployment page shows the commit it built under Commit, as a short SHA and the first line of its message.