Automatic by branch
auto-deploy publishes new versions after pushes to the configured branch. For GitHub and Forgejo projects, Automatic by branch is one of four exclusive update modes. The first build starts during project creation, regardless of the selected mode.
When to enable
Choose Automatic by branch when:
- the configured branch is stable
- the team uses pull requests or review before merge
- every push to the branch should become a new published version
- the application has tests or validation before reaching the watched branch
Avoid enabling it on experimental branches or branches used for local work.
How it works
- the project is created from a connected Git repository
- you choose branch, runtime, version, and commands
- Automatic by branch is selected in the project settings
- the first build starts when the project is created
- a later push to the selected branch starts a new publication when automatic-by-branch updates are enabled
- Zenifra updates the project when publication finishes successfully
In Manual, By Tag, and By Release modes, branch pushes do not publish automatically. You can change the update mode after creation; see GitHub Deployment, Deploy from Forgejo, and the GitHub Builds API.
What to validate
After a push:
- check build logs
- confirm the application responds on the public URL
- review application logs
- validate metrics and HTTP requests
- confirm the published version, if the application exposes commit or version
Common failures
| Symptom | Likely cause |
|---|---|
| Push did not trigger deploy | The mode is not Automatic by branch, the push was made to a different branch, or, on Forgejo, the hook was not delivered |
| Build failed | wrong command, missing dependency, or inconsistent lockfile |
| App crashed after deploy | wrong port, missing variable, or startup error |
| Wrong version is live | push was made to a branch different from the configured one |
Next steps
FAQ
Can I change the update mode later?
Yes. Choose Manual, Automatic by branch, By Tag, or By Release; only one mode can be active. In GitHub projects, use Edit settings on the GitHub deployment card; the GitHub Builds API documents the endpoint. In Forgejo projects, use Deployment mode in the Git repository section or zenifra project source deploy-settings set.
Does Automatic by branch mode exist for OCI?
Not in the same format. OCI projects are updated by changing the published image.
Does the build run on every push?
In Automatic by branch mode, pushes to the selected branch trigger a new publication.
Last updated on