Environment Branches & EnvSync
By default a project has one branch that plays two roles: it's where every task's PR lands, and it's what the release manager tags. Most projects never need more than that. If yours has a real staging step — or several — between "a dev merged this" and "this is what customers run," you can declare an environment ladder: an ordered list of branches, from where work lands to where releases are cut. This page is the practical configuration guide; the ladder's place in the overall branching model is covered in Branching Strategy.
The ladder itself is just project configuration — always available. The EnvSync engine that keeps the rungs in sync automatically is a separate, off-by-default switch on top of it.
The ladder
A ladder is an ordered list of rungs, each a {name, branch} pair:
- The first rung is where every task's PR targets — the branch cell/root PRs merge into. Think of it as the dev trunk.
- The last rung is the release target — the branch the gated release manager commits the version bump + CHANGELOG to and tags.
- Anything in between (a
qaorstagingrung, say) is an intermediate stop.
If a project has never had a ladder configured, nothing changes: its single default_branch is treated as both the first and the last rung. Every existing project keeps behaving exactly as it does today until you deliberately add a ladder on its settings page.
A typical two-rung example
The common case is one intermediate-free split: a dev rung for day-to-day work, a prod rung the release manager ships from.
| Rung | Name | Branch |
|---|---|---|
| 1 (first) | dev | slave |
| 2 (last) | prod | master |
With that ladder set, every task's PR still targets slave as before — but releases are cut and tagged on master, and master no longer needs to be the branch developers work against day to day.
Configuring it
Open a project's settings page (/projects/[id]/settings) and use the Environments card's ladder editor: add rungs, name each one, point it at a real branch, and reorder with the up/down controls. Saving rejects an empty or duplicate branch. This part works whether or not the EnvSync engine below is armed — it's just where the release manager and every task's PR-target branch get resolved from.
EnvSync: keeping the ladder in sync
With ROBOCO_ENV_SYNC_ENABLED on, RoboCo periodically walks each opted-in project's ladder from the last rung down toward the first, merging each rung into the one below it:
- Clean merge — the lower rung is already an ancestor, or the merge applies with no conflict — auto-pushes directly to that lower rung and keeps walking down the ladder.
- Conflict — the cascade stops for that project this cycle. It opens exactly one sync PR (merging the upper rung into the lower) and exactly one coordination task tracking it, routed through the normal delivery flow like any other task — no per-rung spam, no silent drop.
- Only one open sync task per project at a time; a project with one already open is skipped until it resolves.
The cascade's target is always a lower rung — by construction it never pushes to the last (release) rung. That branch only ever advances through the release manager's own promotion below, which still ends at your explicit publish approval. "Only the CEO merges the release branch" holds either way.
How releases use the ladder
When the gated release manager cuts a release, it doesn't just tag the last rung as-is — it first promotes the full chain: it merges every rung from the first down to (but not including) the last into the release 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. See Release Management for the full proposal, approval, and publish flow.
This means the ladder and the release manager work together: EnvSync (when armed) keeps the middle rungs from drifting apart day to day, and the release manager's own promotion step is the final, authoritative sync that happens at cut time regardless of whether EnvSync is on.
Enable it
Set up the ladder itself from a project's settings page → Environments card — this works with the EnvSync flag off or on. To arm the auto-sync cascade, go to Settings → Feature Flags → "Environment sync".
The EnvSync feature flag persists in the settings store and applies on the next backend restart. A project's ladder itself applies to its very next PR/release.
See the environment reference for the full flag list.
What changes when it's on
- A project with no ladder configured is unaffected by any of this, regardless of the flag.
- A project with a ladder but the EnvSync flag off gets the ladder's structural benefits only — PRs target the first rung, releases promote + tag the last rung — with no automatic cascading in between.
- A project with a ladder and the flag on additionally gets the periodic cascade: clean merges flow down the ladder on their own, and a real conflict surfaces as one PR plus one task instead of silent drift.
Docs-site PR labels follow the real target branch
RoboCo's own docs-site repo (the one serving these pages) is configured via ROBOCO_DOCS_SITE_* environment variables rather than a hardcoded repo/URL — the same env-driven pattern as every other project setting. One consequence you'll notice on any project's PRs, not just the docs site: a PR's "to {base}" label is now derived from that PR's real target branch, instead of assuming it's always the project's default. On a project with an environment ladder, that means the label correctly reads to dev for a normal task PR and to master for a release PR, rather than showing the same target for both.
Next
→ Branching Strategy — where the ladder fits in the company-wide branching model. → Release Management — the gated release manager that proposes and publishes releases. → Autonomous Maintenance — the multi-repo CI-watch and dependency-update bot that share the same release executor. → Merge Model — how PRs and branches fit into the delivery lifecycle. → Workstation — where the ladder editor lives. → back to Optional subsystems.