Canary releases¶

Use a canary when a reviewed deployment should receive a controlled slice of app-environment traffic before it becomes the current target for that app environment.

Canary changes an app-environment alias. It does not move the clean public URL. Use Versions and publishing when the clean public URL should move after a canary promote.

The canary workflow is operator-driven: start the split, verify the alias, then promote or roll back.

What Canary Moves¶

Record	Command	Result
App-environment alias	`map canary start`	Splits the alias between the current deployment and the canary deployment.
App-environment alias	`map canary promote`	Makes the canary deployment current and clears the split.
App-environment alias	`map canary rollback`	Clears the split and keeps the current deployment at 100 percent.
Clean public URL	`map publish`	Pins the clean public URL to a reviewed deployment. Canary does not do this.

For customer-visible release work, run the canary against the production app-environment alias. map canary resolves the alias from the canary deployment's recorded app environment, so confirm the deployment belongs to the intended app environment before changing traffic.

Prerequisites¶

Need	How to check
App name or `app:` ref	Use the same app value you use with `map versions <app>` and `map publish <app>`.
Current alias target	Run `map versions <app>` and read the target app-environment alias.
Canary deployment ref	Use the deployment ref from the deploy response, `map versions <app>`, or the release record.
Completed current and canary deployments	Run `map --json status <deployment-ref>` for each deployment. The deploy phase must be `Succeeded` or `Promoted`.
Canary weight	Choose an integer from 1 through 99. Use `promote`, not weight `100`, for full cutover. Use `rollback`, not weight `0`, to end the split.
Verification target	Use the alias hostname returned by `map canary` or shown by `map versions <app>`. Do not use the clean public URL as canary evidence unless it has already been published to the intended route.

For start, Forge selects the alias from the named canary deployment's app ref, account context, and app environment. The alias must already exist and its current target must have reached Succeeded or Promoted.

Keep the deploy status and release review evidence with the canary request. The status view proves phase and app-environment identity; the release review proves which source change the operator intended to expose.

Start a Canary¶

Start with JSON output when the release record needs the exact response:

map --json canary start <app> --deployment-ref <canary-deployment-ref> --weight 10

For interactive use, text output is easier to scan:

map canary start <app> --deployment-ref <canary-deployment-ref> --weight 10

Expected text fields:

action: canary-start
status: ok
app_ref: app:<app> (requested)
alias_app_ref: app:<app>
alias_app_mismatch: no
canary_deployment_ref: <canary-deployment-ref>
alias: <route-pointer-ref>
hostname: <alias-hostname>
current_deployment_ref: <current-deployment-ref>
active_canary: <canary-deployment-ref>
result: 10% canary, 90% current

Stop if alias_app_mismatch is not no. The CLI exits non-zero for this text mode check, but the output is still useful evidence for the operator.

Verify the Split¶

After start, inspect route state:

map versions <app>

The target alias should show the current deployment, alias hostname, canary deployment, and weight:

production (CanaryWeight)  ->  <current-deployment-ref>  <alias-hostname>  [canary <canary-deployment-ref> 10%]

With JSON output, the alias entry includes canary_deployment_ref and canary_weight_pct while the split is active.

Verify application behavior against the alias hostname shown by map canary or map versions <app>. Keep the command output, deployment refs, weight, alias hostname, and verification result together.

Promote or Roll Back¶

Promote when the canary should become the current alias target:

map --json canary promote <app> --deployment-ref <canary-deployment-ref>

Rollback when the current alias target should remain at 100 percent:

map --json canary rollback <app> --deployment-ref <canary-deployment-ref>

After either command, run:

map versions <app>

The alias should no longer show canary_deployment_ref or canary_weight_pct. A promote makes the canary deployment the alias current target. A rollback leaves the previous current deployment as the alias current target.

Publish After Promote¶

If users reach the clean public URL, canary promote is not the final publish step. Publish the promoted deployment only after the operator has reviewed the release evidence:

map publish <app> --deployment-ref <promoted-deployment-ref> --expected-sha <reviewed-sha>

Use --expected-sha when a human reviewed a specific commit. Forge rejects the publish if the selected deployment records a different source SHA.

Stop and Investigate¶

Symptom	What it means	Next step
`--weight` is rejected	The weight is not 1 through 99.	Choose a real split, or use promote/rollback to end a split.
`missing canary_deployment_ref`	The request did not name a candidate deployment.	Rebuild the command from the reviewed deploy evidence.
`missing weight_pct`	`start` needs a weight.	Add `--weight <1-99>`.
Deployment is not found	The deployment ref or the selected app-environment alias is not recorded in this account context.	Re-check the deployment ref and `map versions <app>`.
Target is not canary-eligible	The current alias deployment or canary deployment has not reached `Succeeded` or `Promoted`.	Wait for a completed deploy or deploy a fixed commit.
`alias_app_mismatch` is not `no`	The returned alias belongs to a different app than the requested app.	Stop before further traffic changes. Keep the canary output and investigate app identity.
`map versions` does not show the split	The canary action did not change the alias you are inspecting.	Compare the returned alias, app ref, app environment, deployment ref, and weight.
Clean public URL does not change	Canary does not move the clean public URL.	Use `map publish` after a successful promote when the clean URL should move.
Promote or rollback reports no active canary	The alias no longer has a split, or the deployment ref points at the wrong alias.	Re-run `map versions <app>` and use the active canary deployment ref if a split exists.

Evidence to Keep¶

map versions <app> before start, after start, and after promote or rollback;
map --json status <deployment-ref> for the current and canary deployments;
map --json canary ... response for each canary action;
app, app-environment alias, alias hostname, current deployment ref, canary deployment ref, and weight;
release review evidence for the source change;
verification result from the alias hostname;
publish command output when the clean public URL is moved after promote.