Channels

A channel is a pointer with a name. It says which shipped version an app is serving, and promoting is the act of moving it. Nothing is rebuilt between one channel and the next — the bytes that were tested are the bytes that go live, which is the whole reason the platform separates shipping from promoting.

You start with one

Every app is created with a single channel called edge, and carlos deploy lands there. That is enough for most apps: you deploy, and it is live. To see where things stand:

carlos channels -app hello

Nothing is ever promoted onto the entry channel. Deploys land there, and promotion moves a version from it to whatever comes next — so with one channel there is no promotion step at all.

Adding a stage in front of production

When you want a version to sit somewhere before a wider audience sees it, declare a pipeline. The starter template adds a production channel behind edge:

carlos pipeline init -app hello -template edge-production

That gives production a 24-hour bake window, a passkey requirement on promotion, and an approval on any change to those rules — so the protection cannot be quietly removed later either. The other template, full-ladder, sets up edge → beta → stable with bakes of 24 and 72 hours and the passkey on stable.

Once a pipeline exists, deploys still land on edge and you move a version forward by naming it:

carlos promote -app hello a1b2c3d production

A channel is entered from the one immediately before it and no other, so "it ran on edge for a day first" is a fact about the bytes rather than a claim about process. Promoting the same version twice succeeds and changes nothing.

The rules a channel can carry — bake windows, passkeys, approval counts — are all editable after the fact with carlos pipeline, and carlos promote documents the rest of its own flags.

Putting a version back

Rollback points a channel at whatever it was serving before:

carlos rollback -app hello production

The outgoing version goes onto the channel's history as it leaves, so running the same command again returns you to where you started — useful when the rollback turns out to be the wrong call. A bake window does not delay it: a box already has the version it is going back to, so there is nothing to hold.

Two things are worth doing before you need this. Give your ships a -label people can read, because that is what you will be squinting at during a rollback. And get familiar with carlos releases while nothing is on fire: it answers "what is there to run", where carlos channels answers "what is running".

What reaching stable means

The full-ladder shape has a stable channel at the top, and a promotion onto it can cut a semver tag: one name pointing at one release, with the changelog of every iteration that led there compiled into it.

That happens when the version being promoted is an iteration of a target rather than a commit sha, so set the target once:

carlos version target -app hello 0.5.0

From then on carlos ship with no -version mints the next iteration under it. Promote a sha-named build to stable instead and the promotion still lands. There is no tag to cut, and the promotion says so.

Tags are a naming convenience and an audit record, nothing more. No part of getting your app running reads one, so an app that never uses them loses nothing.

Full flags for the commands on this page: channels and rollback.