Getting started
Automatic deploys
How it works#
You push to the branch
For example
git push origin main, or merging a pull request intomain. GitHub tells the platform within seconds.A build of that exact commit starts
It appears on the service's Builds tab within seconds, where you can follow its log live.
It deploys when the build succeeds
Your current version keeps serving visitors while the new one builds and starts. If the new version doesn't start, the previous one keeps running and you get an email saying what went wrong.
On by default
Every service built from a GitHub repository deploys automatically, including services created before this feature existed. You can turn it off per service.
Which pushes deploy#
| You… | Deploys? |
|---|---|
| push commits to the service's branch | Yes: the newest commit |
| merge a pull request into that branch | Yes |
| push to any other branch | No |
| push a tag (e.g. v1.2.0) | No |
| delete the branch | No |
push a commit whose message contains [skip deploy] | No: see Skipping a push |
The branch is the one shown on the service's Settings tab, under Build & source. If several services in a project are built from the same repository and branch (say an API and its worker), one push deploys all of them.
Pushing several times in a row doesn't queue up a build for every push. The newest commit wins: while one build is running, further pushes wait, and when it finishes only the latest commit is built.
Skipping a push#
To push without deploying (for example documentation changes, or work in progress), put one of these anywhere in the commit message:
Update the README [skip deploy]All of these work, in any capitals: [skip deploy], [deploy skip], [skip ci], [ci skip]. Only the last commit of a push is checked. When you're ready, push again without the tag, or deploy by hand.
Turning it off for a service#
Open the service → Settings → Build & source, untick Build and deploy every push, and press Save changes. Pushes then do nothing for that service, and you deploy by hand. Tick it again at any time.
Deploying by hand#
You can still deploy whenever you like, for example after changing settings:
| You want to… | Do this | What happens |
|---|---|---|
| Ship the latest code now, or apply new settings | Settings → Redeploy (or Builds → Trigger build) | Builds the latest commit on the branch, then deploys it. Unsaved settings are saved first. |
| Apply changed environment variables only | Deployments → Redeploy | Restarts the current version with the new values. No rebuild, so it's faster. |
Changing the branch or repository#
Open the service → Settings → Build & source. The Branch list shows your repository's real branches, with its default marked; pick one, then Save changes (or Save and redeploy). From then on, pushes to the new branch deploy.
Shared by every service in the project
The repository and branch belong to the project, so changing them changes what every service in that project builds. The Settings page tells you when other services share it. To deploy a different repository, create a new project for it.
What it needs#
- Your workspace's GitHub is connected (sidebar → GitHub) and can see the repository. A push has no person pressing a button, so it builds through the workspace's connection.
- For a GitHub organisation that gave the app access to selected repositories only, the repository must be one of them. An owner of the organisation can change this on GitHub: organisation → Settings → GitHub Apps → Atom Code Connect → Configure → Repository access.
If a push is ever missed (for example GitHub had an outage), it isn't lost: every 30 minutes the platform compares each service's branch with what it last built, and builds anything newer.
Emails when something fails#
When a build or deploy fails, the people involved get one email with the reason and a link to the log:
- whoever pressed Redeploy or Trigger build,
- whoever pushed the commit, if they're a member of the workspace,
- the workspace's owner.
A service that keeps failing sends at most one email every 10 minutes; the next email says how many more failures happened in between. Successful deploys don't send email.
To stop these emails for yourself, open Account settings in the sidebar and untick Email me when a build or deploy fails. The setting is per workspace.
My push didn't deploy#
Check, in this order:
- The last commit's message doesn't contain
[skip deploy]or one of the other skip tags. - You pushed to the branch shown on the service's Settings tab.
- Build and deploy every push is ticked on that Settings tab.
- The Builds tab: a build may be running or have failed. A failed build shows the reason.
- The workspace's GitHub can see the repository (What it needs).
Still nothing? Wait up to 30 minutes for the automatic check, or deploy by hand with Settings → Redeploy. If that works but pushes never do, tell the platform team.