Instance Lifecycle
An instance is created when a branch appears, shut down when nobody uses it, and eventually cleaned up entirely. Most of this happens on its own. This page explains what runs automatically, what the thresholds are, and how to keep an instance you still need.
Creation
When zCICD discovers a new branch and the repository has Initialize new Branches enabled, it prepares an instance: checks out the source, generates the Docker configuration, builds the images, starts the containers and creates the database.
Where the database comes from is set per repository by New Instance Mode — either a restored dump or an empty database with demo data. See Repositories.
Release branches are excluded from automatic preparation.
Cycling down: shutdown after inactivity
Running instances that nobody is using waste memory and CPU, so zCICD stops them.
A scheduled job checks development machines and shuts down any instance where:
- the instance is in dev mode
- its containers are actually running
- nothing has accessed it for longer than Cycle Down After Seconds (default: 3600, one hour)
- no task is currently running on it
Shutting down means the containers are killed. The database, filestore and volumes are left untouched — the next access starts it again with everything intact.
You can change the threshold per instance with Edit cycle down on the instance.
Only instances on machines of type Development-Machine are cycled down. Production machines are never touched.
What counts as access
Last access is tracked in a file written when the instance is used, not by Odoo activity alone. Anything zCICD does that touches the instance — including finishing a build — refreshes it, which is why an instance does not get cycled down out from under a long-running operation.
Cleanup: deactivation after neglect
Cycling down saves memory. Cleanup saves disk.
The repository setting Cleanup after days (default: 20) controls it. Once a day, zCICD looks for branches in the repository whose instances have not been accessed for that many days, and:
- sets the branch to inactive
- tears down its instances including their Docker volumes (
odoo down -v)
Freeing volumes reclaims the disk. The instance is rebuilt from the dump the next time it starts.
Three protections apply:
- Release branches are never cleaned up. Branches belonging to a release, and release item branches, are filtered out.
- Production is never touched. Volume removal is hard-guarded to machines of type Development-Machine, independently of the branch filter.
- Recently reactivated branches are protected. The reactivation date counts as access, so a branch you just revived does not get cleaned up again immediately.
Set Cleanup after days to 0 to disable cleanup entirely for a repository.
Cleanup removes volumes, not dumps. Anything that existed only inside the instance's database and was never dumped is gone. If an instance holds state you care about, take a Backup before it goes idle.
Reviving a branch
A deactivated branch is not deleted — it is hidden. It comes back in two ways:
On push. If the repository has Revive Branch on push enabled, pushing a commit to a deactivated branch prepares a new instance for it automatically.
By hand. Clear the Active filter in the branch list, open the branch, and toggle Active back on.
Either way the instance is rebuilt from scratch, since its volumes were freed.
Rebuilding versus updating
When new source arrives, zCICD decides what to do based on whether a database already exists:
- No database yet (or a forced dump preparation) → prepare a whole new instance, including checkout
- Database exists → run an Odoo update against the existing instance
This is why the first push to a branch takes much longer than later ones.
Tearing down by hand
| Action | Effect | Reversible |
|---|---|---|
| Restart | Restarts containers | — |
| Active toggle | Deactivates the branch | Yes |
| Free Volumes (down -v) | Removes Docker volumes, freeing disk | Rebuilt on next start |
| Delete Instance | Destroys the instance entirely | No |
Delete Instance requires typing the instance name to confirm. All four are covered in Branch Actions.
Settings summary
| Setting | Where | Default | Controls |
|---|---|---|---|
| Initialize new Branches | Repository | on | Auto-create instances for new branches |
| New Instance Mode | Repository | Restore Dump | Where a new database comes from |
| Cleanup after days | Repository | 20 | Deactivation and volume freeing. 0 disables |
| Revive Branch on push | Repository | off | Rebuild deactivated branches on push |
| Cycle Down After Seconds | Instance | 3600 | Shutdown after inactivity |
| Machine type | Machine | — | dev machines are cycled down and cleaned up; production machines are not |
Troubleshooting
My instance keeps stopping. That is cycle-down doing its job after an hour of inactivity. Raise Cycle Down After Seconds on the instance if you need it up longer, or simply open it again — starting is quick, because only the containers were stopped.
My branch disappeared from the list. It was probably deactivated by cleanup after 20 days. Clear the Active filter to find it, then toggle Active.
A revived branch takes a long time to start. Expected — its volumes were freed, so the database is being restored from the dump again.
An instance was not cycled down. Check that it is in dev mode, that no task is running on it, and that its machine is a Development-Machine.