Branching Strategy
RoboCo treats a project's branches as a release railroad, not a free-for-all. By default every project has one branch that plays two roles: it's where task PRs land, and it's where the release manager cuts the next version. When you outgrow that — when work needs to bake on a dev or qa rung before it reaches prod — you can declare an ordered environment ladder instead. The ladder is company-level structure: it decides where every task's PR targets, where releases are tagged, and how the release executor promotes work up the chain.
The single-branch default
A project that has never declared a ladder behaves exactly as before. Its default_branch is treated as both the head rung (where PRs land) and the prod rung (where releases are cut). Nothing moves, nothing breaks, and existing projects keep behaving byte-for-byte until you deliberately add rungs.
The ladder
A ladder is an ordered list of {name, branch} rungs:
| Position | Name | What it means |
|---|---|---|
Index 0 | head / dev rung | Where every task's PR merges. The per-agent clone also points here. |
| Middle rungs | qa, staging, etc. | Optional stops between dev and prod. |
Index -1 | prod / release rung | Where the gated release executor commits the version bump and tags the release. |
A typical two-rung ladder
| Rung | Name | Branch |
|---|---|---|
| 1 (head) | dev | slave |
| 2 (prod) | prod | master |
With this ladder, day-to-day PRs still target slave, but releases are cut and tagged on master. master is no longer the branch developers work against by default.
How releases climb the ladder
When the gated release manager cuts a release, it does not just tag the prod rung as-is. It first promotes the full chain: it merges every rung above prod into the prod branch, in order, before writing the version bump and CHANGELOG entry. If any of those merges conflicts, the release aborts before anything is committed — you get a clean failure, not a bad tag.
Keeping the ladder in sync (EnvSync)
The ladder itself is just project configuration. The EnvSync engine that keeps the rungs in sync is a separate, off-by-default flag (ROBOCO_ENV_SYNC_ENABLED). When armed, EnvSync periodically cascades the ladder from the last rung down toward the first, merging each rung into the one below it:
- A clean merge auto-pushes to the lower rung and keeps walking down.
- A conflict stops the cascade for that project and opens exactly one sync PR plus one coordination task — never per-rung spam.
- EnvSync never targets the prod rung; it only merges into lower rungs. The prod rung still advances only through your explicit release approval.
See Environment Branches & EnvSync for the full configuration guide.
Setting it
Open a project's settings page in the panel and use the Environments card's ladder editor to add, name, reorder, and remove rungs. Saving rejects empty or duplicate branches. The ladder itself applies on the very next PR or release; EnvSync applies after the next backend restart once the flag is flipped.
A null ladder is not an error. RoboCo synthesizes a single-branch ladder from default_branch at read time, so every existing project keeps behaving exactly as it does today until you deliberately split it.
Next
→ Environment Branches & EnvSync for the toggle and the sync cascade · Autonomous Maintenance for the gated release manager that promotes the ladder at cut time · The merge model for how task PRs flow up to master.