Crucible / Docs

Promote and schedule channel updates

A channel divides consumers into 256 stable buckets, 00 through ff. Each bucket points to a signed registry release. A host chooses and persists its bucket; the publisher chooses which buckets advance.

Channels require the generated static origin to be readable over HTTP or HTTPS. They are not available from a filesystem-only or smart-Git-only registry.

#Initialize a channel

Initialize all buckets at a known good release while publishing it:

apr release 2026.8.0 \
  --registry acme \
  --key-id release \
  --channel stable \
  --init-channel \
  --cache-url https://packages.example.com/acme/ \
  --upload-url s3://acme-packages/registry

Consumers opt into the channel when the registry is configured:

apm registry add https://packages.example.com/acme/ \
  --name acme \
  --channel stable \
  --trust-key 'acme:Ed25519:BASE64_KEY'

The selected bucket and monotonic release floor are durable consumer state. Refreshing metadata does not randomly move a host between rollout rings.

#Start a progressive rollout

The release convenience flags can publish a complete release and then expose its planned channel pointers. An unpublished release stage never advances partitions. For an explicit review boundary, first stage and finalize the release as described in publishing, then run apr channel advance and upload the resulting pointers.

To publish the next complete release and advance eight buckets:

apr release 2026.8.1 \
  --registry acme \
  --key-id release \
  --channel stable \
  --count 8 \
  --cache-url https://packages.example.com/acme/ \
  --upload-url s3://acme-packages/registry

--count 8 means eight additional lowest-numbered buckets that do not already point at 2026.8.1. It does not mean “make the target total eight.” Repeating the command with another --count 8 advances eight more.

For named canary rings, select exact buckets in decimal or hexadecimal:

apr channel advance stable 2026.8.1 \
  --registry acme \
  --partitions 0x00,0x10,0x20,0x30 \
  --key-id release
apr origin upload \
  --registry acme \
  --upload-url s3://acme-packages/registry

Exactly one of --count and --partitions is required for an advance. A standalone apr channel advance changes the local static surface; follow it with apr origin upload so consumers can see the new pointers.

Inspect the map at any point:

apr channel status stable --registry acme
aos hub registry channel acme/cdn stable \
  --hub https://hub.example.com

The Hub command is a read operation against an indexed hosted registry. Use the local apr status as the producer source of truth before upload and the Hub or public origin as the post-upload view.

#Schedule later rings

apr deliberately has no wall-clock scheduler. Use the organization's CI, release controller, or a systemd timer to run one serialized, audited step:

apr channel advance stable 2026.8.1 \
  --registry acme \
  --count 24 \
  --key-id release
apr origin upload \
  --registry acme \
  --upload-url s3://acme-packages/registry
apr channel status stable --registry acme

An unattended job should:

  1. verify the exact target release and current channel map;
  2. acquire the organization's single-publisher lock;
  3. obtain a short-lived upload credential and signing-key access;
  4. advance a bounded number of buckets;
  5. upload the static origin;
  6. check the public channel map and package health before recording success.

Use JSON output for machine checks and retain it with the deployment record:

apr --json channel status stable --registry acme
aos --json hub registry channel acme/cdn stable \
  --hub https://hub.example.com

Do not schedule apr channel advance without the matching upload step. The local command can succeed while the public registry remains unchanged.

#Complete or stop a rollout

Advance all remaining buckets by asking for up to 256 additional buckets:

apr channel advance stable 2026.8.1 \
  --registry acme \
  --count 256 \
  --key-id release
apr origin upload --registry acme \
  --upload-url s3://acme-packages/registry

Advances are monotonic. Do not point a bucket back to an older release; clients retain a release floor and reject rollback. To stop a bad rollout, stop advancing it, publish a corrected release with a higher version, and advance affected buckets to that release. See Manage trust and incidents for removing or revoking the bad package metadata as part of the fix-forward release.