# Channels > Named pointers to released builds, and the rules for naming and targeting them. Canonical: https://docs.extension.dev/builds/channels This page as Markdown: https://docs.extension.dev/builds/channels.md Section: Console: build and release Siblings: [Console overview](https://docs.extension.dev/console/overview.md) · [Usage and limits](https://docs.extension.dev/console/usage.md) · [Builds](https://docs.extension.dev/builds/overview.md) · [Releases](https://docs.extension.dev/builds/releases.md) · [Store releases](https://docs.extension.dev/builds/store-releases.md) · [Promote gates](https://docs.extension.dev/builds/promote-gates.md) · [Integrity](https://docs.extension.dev/builds/integrity.md) Map of every page: https://docs.extension.dev/llms.txt · Whole corpus: https://docs.extension.dev/llms-full.txt --- # 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": "", "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 `-`, 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](/builds/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](/publish/overview). ## 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 | `-`, 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](/builds/promote-gates). - **`canary` promotes from but not to.** `canary` is the old name of `preview`, kept as a source alias only. Promote to `preview`, or create a channel of your own for a separate track. - **Expected `beta` is missing.** It is not seeded. Create it before promoting to it. A promote to an undeclared channel is refused with `404 UNKNOWN_CHANNEL` and never creates one. - **A per-browser name was refused.** `chrome-preview` is how the platform records `preview` for Chrome, not a channel you promote to. Promote to `preview` and name `chrome` in `browsers`. - **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. ## Next - [Releases](/builds/releases) - [Promote gates](/builds/promote-gates) - [Publishing](/publish/overview)