Channels
You have a build and need to decide where it lands. A channel is a named pointer to one released build; promoting a build into a channel is what releases it.
The seeded channels
There is exactly one seeded channel: preview. stable always exists as a promote target. Nothing else is seeded: 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 of the body lands in stable. The console's new release form starts on preview. Name the channel and both go where you said.
canary is a legacy alias of preview. A project that still references canary resolves it to preview rather than failing.
Naming
Channel names match ^[a-z0-9-]+$. 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.
Promoting to a channel that does not exist
A promotion names a channel, and the channel is checked before anything is dispatched, metered or written.
- A channel the project does not declare is refused with
404 UNKNOWN_CHANNEL. The message lists the channels the project does declare, which always includestableandpreview. - A channel list that cannot be read at that moment is refused with
409 CHANNEL_STATE_INDETERMINATE. The gate refuses rather than promoting into a name it cannot check. Retry.
A channel you created a second ago promotes, because this gate reads the same channel record the console writes. See Promote gates.
What a channel records
Each channel records the sha of the build it currently serves, a color, and a description. Promotion moves the pointer; the artifacts are byte for byte the artifacts of the promoted build, which is what makes a channel testable.
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, in four values:
| 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 |
A failure outranks the rest, so one browser's failed run keeps the channel out of live instead of averaging away. When the run history cannot be read the channel reads unconfirmed, never live: an unreadable answer downgrades a claim and never manufactures one.
Channels and environments
A channel bound to an environment accepts only builds stamped with that environment. Promotion does not rebuild, so a build carries its stamp into whatever channel it enters. A mismatch is refused with BUILD_ENV_MISMATCH, see Promote gates.
Channels and stores
Store submissions read from a channel. Submitting with --channel stable takes whatever build stable currently holds. See Publishing.
When it fails
- Channel name rejected. The name does not match
^[a-z0-9-]+$. 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.
canarybehaves likepreview. It ispreview. Create a channel of your own if you want a separate track.- Expected
betais missing. It is not seeded. Create it before promoting to it. A promote to a channel the project never declared 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.