Channels
A channel is a named pointer to one released build. Reach for one when you have a build and need to decide where it lands: promoting a build into a channel is what releases it.
Quick start
POST /api/projects/{id}/releases
{ "buildId": "<short-sha>", "channel": "preview" }The build's artifacts become what preview serves, byte for byte, and one promote run dispatches per browser.
How it works
One seeded channel
Exactly one channel is seeded: preview. stable always exists as a promote target. beta does not exist until you create it, and every other channel is user-created.
The two promote surfaces default differently. An API promotion that leaves channel out lands in stable. The console's new release form starts on stable once stable has shipped, else on the first channel that has, else on preview. Name the channel and both go where you said.
canary is the name preview carried before. The promote gate accepts canary as a source channel under its own name, so a project whose records still carry it promotes from it. It is never rewritten to preview, and as a target it must be declared like any other channel.
One name across browsers
A channel is one name across browsers. The platform records it once per browser, under the key <browser>-<channel>, which is the shape a release id has: chrome-preview is the preview channel as Chrome holds it. To release one browser only, promote to the channel and name that browser in browsers.
The channel is checked first
A promotion names a channel, and the channel is checked before anything is dispatched, metered or written. A channel you created a second ago promotes, because the gate reads the same record the console writes. The codes are in Promote gates.
What a channel records
Each channel records the sha of the build it serves, a color and a description. Promotion moves the pointer and never rebuilds, so the artifacts are the promoted build's artifacts, byte for byte.
A pointer is not a shipped channel
The pointer is written when the promote workflow is dispatched, so the pointer alone proves a request was made. What the channel reports comes from the promote run's conclusion instead. A failure outranks the rest, so one browser's failed run keeps the channel out of live. When the run history cannot be read, the channel reads unconfirmed, never live.
Channels and environments
A channel bound to an environment accepts only builds stamped with that environment. stable is bound to production by default and every other channel to staging. A build carries its stamp into whatever channel it enters, and a mismatch is refused with BUILD_ENV_MISMATCH.
Channels and stores
A store submission names a buildId and a channel, and channel defaults to stable. The submission run compares the build against the channel's pointer and warns on a mismatch. See Publishing.
Reference
Naming
| Rule | Value |
|---|---|
| Channel name | ^[a-z0-9-]+$ |
| Promote target | Starts with a letter or digit, at most 41 characters |
| Per-browser record key | <browser>-<channel>, such as chrome-preview |
| Seeded channel | preview |
| Always a promote target | stable |
| Legacy source alias | canary, accepted as a source channel only |
Status
| Status | What it means |
|---|---|
live | Every browser in the channel has a promote run that concluded success |
promoting | A run is still going |
failed | A run concluded anything other than success |
unconfirmed | No run answers for that pointer, or the run history could not be read |
Refusals
| Code | Status | Meaning |
|---|---|---|
UNKNOWN_CHANNEL | 404 | The project does not declare the channel. The message lists the ones it does, which always include stable and preview |
CHANNEL_STATE_INDETERMINATE | 409 | The channel list could not be read at that moment. Retry |
BUILD_ENV_MISMATCH | 409 | The build's environment stamp does not match the channel's environment |
When it fails
- Channel name rejected. The name does not match
^[a-z0-9-]+$. Use lowercase letters, digits and hyphens only. - Promotion refused with a code. The build failed a gate: wrong environment stamp, unknown sha or a quota cap. Every code and its fix is in Promote gates.
canarypromotes from but not to.canaryis the old name ofpreview, kept as a source alias only. Promote topreview, or create a channel of your own for a separate track.- Expected
betais missing. It is not seeded. Create it before promoting to it. A promote to an undeclared channel is refused with404 UNKNOWN_CHANNELand never creates one. - A per-browser name was refused.
chrome-previewis how the platform recordspreviewfor Chrome, not a channel you promote to. Promote topreviewand namechromeinbrowsers. - The channel holds a build but reads
unconfirmed. The pointer moved and no promote run answers for it. Open the run from the release page, or promote again once the run history is readable.