Channels and releases

A release is one build you pushed: a name like 1.2.0, for one platform, signed and immutable. A channel is a named pointer, like stable or beta, that points at one release of one platform. Players install and update from a channel, never from a release directly.

You push releases whenever you like. Players only get one when you move a channel to it.

ReleasesCopy Anchor Link

Each push creates a release. Depot gives it an id (rel_…) and a sequence number. Sequence numbers count up per game and platform, starting at 1, and never go down. The launcher uses them to tell newer from older.

A release has a status:

List and inspect releases:

depot release list --game my-game
depot release list --game my-game --platform windows-x64
depot release show --game my-game --release-id rel_0123456789abcdef0123456789abcdef

release list shows each release's name, platform, sequence, status, package, size, signing key and who pushed it. release show prints one published release with its signed envelope. Both print JSON.

ChannelsCopy Anchor Link

A channel belongs to one platform. stable on windows-x64 and stable on macos-arm64 are two separate channels, and you move each one on its own. That lets you ship a fix to one platform without touching the others.

Your store page installs from one channel, stable unless you set another with depot game page --channel. You can make more channels for testers, such as beta.

Look at a channelCopy Anchor Link

depot channel show --game my-game --platform windows-x64 --channel stable

This prints the release the channel points at, its name and sequence, and the channel's revision. The revision goes up by one on every move.

Without --platform, channel show and channel set use the platform of the machine you run them on.

Move a channel (promote)Copy Anchor Link

The usual way is to move the channel as part of the push:

depot push --game my-game --platform windows-x64 --release 1.3.0 \
  --input build/windows/ --channel stable --note "The winter update."

To promote a release you already pushed, for example one you tested on beta, use depot channel set with its release id:

depot channel set --game my-game --platform windows-x64 --channel stable \
  --release-id rel_0123456789abcdef0123456789abcdef \
  --note "The winter update, now for everyone."

Moving a channel that doesn't exist yet creates it.

The note is what players see under What's new on your store page. The page shows the latest releases on its channel, newest first, each with its note. Rollbacks aren't listed there.

Moves are safe to retryCopy Anchor Link

Every move is a compare-and-swap on the channel's revision. The CLI reads the current revision, then asks Depot to move the channel only if it hasn't changed. If someone else moved it in the meantime, you get 409 revision_mismatch with the channel's current release, and nothing moves. Read the channel again and decide.

This also means a retried request can never move a channel twice.

Roll backCopy Anchor Link

Moving a channel to a release with a lower sequence number is a rollback. Depot refuses it unless you ask for it:

depot channel set --game my-game --platform windows-x64 --channel stable \
  --release-id rel_0123456789abcdef0123456789abcdef \
  --allow-rollback

Without --allow-rollback you get a 409 that names both sequence numbers.

What a rollback does for players:

• New installs get the release the channel points at now.
• Players who already installed the newer release keep it. The launcher refuses to install a release older than the one on the machine, because an attacker could otherwise replay an old, vulnerable build. A player using the CLI can accept it on purpose with depot update --allow-rollback.

To move everyone off a bad build, push the good build again under a new name, for example 1.3.1, and move the channel to it. It gets a higher sequence number, so every player's next update installs it. Because the chunks are already on Depot, the push uploads almost nothing, and players' updates download only the chunks that differ from what they have.

depot push --game my-game --platform windows-x64 --release 1.3.1 \
  --input build/windows-1.2.0/ --channel stable \
  --note "Back to 1.2.0 while we fix a crash in 1.3.0."

HistoryCopy Anchor Link

Every move is recorded with who made it, the release it moved from and to, whether it was a rollback, and the note. You can read a channel's history through the API at GET /v1/organizations/{org}/games/{id}/channels/{platform}/{name}/history. Moves also appear in your organization's audit log, which owners and admins can read:

depot org audit

PermissionsCopy Anchor Link

Owners, admins and publishers have all three. Members can read. API keys have only the permissions you give them. See CI and agents.