Appearance
Deployment Process
This document explains how deployment works in our monorepo, including the flow from pull requests to production, the use of QA and canary stages, and how hotfixes are handled.
PR-based Staging (Autodeploy)
- When a developer creates a pull request (PR) into
main, an autodeploy process creates a unique stage for that PR, namedpr-<number>. - This stage runs in a QA-like environment, sharing persistent resources such as databases, storage buckets, and distributions with the main QA stage.
- This allows for isolated testing of each PR while maintaining access to shared infrastructure.
QA Stage
- When a PR is merged into
main, the correspondingpr-<number>stage is deleted. - The
mainbranch is then automatically deployed to the QA stage. - QA is used for internal testing and validation before promoting changes to canary or production.
Canary Deployments
- Canary is a special stage used to test new changes with a subset of real users (typically 10%).
- Deployment to canary is manual: you can pick any stable commit from the repository to deploy to canary.
- User assignment to canary is handled automatically by a CloudFront edge function, which sets a cookie to route 10% of users to the canary deployment.
- Canary and production share the same hard resources (databases, storage, etc.), so canary is a true preview of production behavior.
Production Deployments
- When ready, you can promote any commit (often the one running in canary) to production.
- Production and canary use the same infrastructure, ensuring consistency between environments.
Hotfixes
- In urgent cases, you can deploy hotfixes directly to production by selecting the desired commit and promoting it.
- This allows for rapid response to critical issues without waiting for the full QA/canary process.
Versioning and Tagging Conventions
Deployment stages are mapped to version tags and branch events as follows:
PR Stage:
- Triggered when a pull request is opened to
main. - Stage name:
pr-<number> - Auto-deployed for each PR, isolated but shares QA resources.
- Triggered when a pull request is opened to
QA Stage:
- Triggered when code is pushed to the
mainbranch. - Stage name:
qa - Auto-deployed from
main, used for internal QA.
- Triggered when code is pushed to the
Canary Stage:
- Triggered by a tag matching the pattern:
v<semver>-canary.<number>(e.g.,v1.2.3-canary.0). - Stage name:
canary - Manual deployment, used for ~10% of users, shares production resources.
- Tagging convention:
vX.Y.Z-canary.N
- Triggered by a tag matching the pattern:
Production Stage:
- Triggered by a tag matching the pattern:
v<semver>(e.g.,v1.2.3). - Stage name:
prod - Manual deployment, used for all users, shares production resources.
- Tagging convention:
vX.Y.Z
- Triggered by a tag matching the pattern:
Hotfixes:
- Deploy a hotfix directly to production by creating a new semver tag (e.g.,
v1.2.4) and triggering a production deployment.
- Deploy a hotfix directly to production by creating a new semver tag (e.g.,
These conventions ensure that deployments are predictable and traceable, and that canary and production releases are always tied to explicit, versioned tags.
Summary Table
| Stage | Trigger | User Base | Resources | Notes |
|---|---|---|---|---|
| PR Stage | PR opened | None | QA shared | Isolated for each PR, auto-deleted |
| QA | PR merged to main | Internal | QA shared | Auto-deployed from main |
| Canary | Manual (any commit) | ~10% of users | Prod shared | User assignment via CloudFront cookie |
| Production | Manual (any commit) | All users | Prod shared | Can promote hotfixes directly |
This deployment process enables safe, flexible, and rapid delivery of changes, with robust support for testing, canary releases, and emergency hotfixes.