How to Run a Canary Deploy With GitLab CI/CD

A canary sends a small share of traffic to the new version, and a separate manual job promotes it to the full fleet.

Deploy the canary at a low weight, watch it, then promote with a manual promote job that scales the new version to 100% and retires the old one.

Steps

• Deploy the new version at a small weight (e.g. 10%).
• Observe error rate and latency on the canary.
• Add a manual promote job to shift to 100%.
• Add a manual abort job to roll the weight back to 0%.

.gitlab-ci.yml

canary:
  stage: deploy
  script:
    - ./set-weight.sh --version "$CI_COMMIT_SHORT_SHA" --weight 10
  environment:
    name: production

promote:
  stage: deploy
  needs: [canary]
  when: manual
  script:
    - ./set-weight.sh --version "$CI_COMMIT_SHORT_SHA" --weight 100
  environment:
    name: production

Gotchas

• Give the canary enough traffic and time to surface real errors before promoting.
• Automate the abort path so a bad canary does not depend on someone watching a dashboard.

Related guides