CI/CD & Artifact Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The RoundingWell frontend CI/CD system manages the lifecycle of the application from code commit to multi-organization deployment. The process is tag-based, where CircleCI publishes release artifacts from version tags, and deployment processes consume those artifacts to update various environments across stages like dev, qa, prod, and sandbox.
Sources: README.md:27-28, scripts/deploy.js:180-185
Release Management
Releases are driven by an automated tagging process that ensures environment immutability and version consistency. The system enforces strict branching rules, allowing releases only from develop or release/* branches.
Versioning and Tagging
The release script generates tags following the format vYYMMDD.N (e.g., v260212.1). These tags are treated as immutable; once a tag exists on the remote origin, it cannot be moved or reused.
Sources: README.md:38-44, scripts/release.js:160-175
Release Flow Logic
The release process involves several safety checks before a tag is created and pushed:
- Clean Tree: Ensures no uncommitted local changes exist.
- Branch Validation: Confirms the current branch is
developor arelease/branch. - Upstream Sync: Validates that local HEAD matches the upstream remote branch.
- Reachability: Ensures the commit to be tagged is already present on a remote allowed branch.
Sources: scripts/release.js:63-155, README.md:46-47
Artifact Pipeline
The pipeline separates the "Build" and "Deploy" phases using S3-backed artifacts. This allows a single build to be promoted across multiple environments without rebuilding the source code.
Publishing Artifacts
Artifacts are bundled as .tar.gz files and uploaded to an S3 bucket (rw-frontend-artifacts-dev by default). Each artifact is accompanied by a SHA256 checksum file to ensure integrity during the download phase.
Sources: scripts/publish-artifact.js:11-25, scripts/publish-artifact.js:90-95
Downloading and Verification
During deployment, the system downloads the specific versioned artifact and validates it against the stored checksum.
Sources: scripts/download-artifact.js:56-65
| Component | Default Value / Path | Description |
|---|---|---|
| Artifact Bucket | rw-frontend-artifacts-dev | S3 bucket for storing versioned builds. |
| Artifact Path | /tmp/dist.tar.gz | Local path for the compressed build. |
| Checksum Path | /tmp/dist.tar.gz.sha256 | Path for the SHA256 integrity hash. |
| Artifact Key | [prefix]/[tag]/dist.tar.gz | S3 key structure for versioning. |
Sources: scripts/publish-artifact.js:11-16, scripts/download-artifact.js:11-16
Deployment Orchestration
Deployment involves resolving target organizations via CloudFormation tags and synchronizing built assets to environment-specific S3 buckets.
Organization Resolution
The system queries AWS CloudFormation to find stacks that match a specific stage and optional organization tag. It specifically looks for an output named WebsiteBucket to identify the destination for assets.
Sources: scripts/deploy.js:65-80
Deployment Execution Flow
A deployment to an organization follows a specific sequence to ensure availability:
- AppConfig Generation: A unique
appconfig.jsonis generated for the specific organization using secrets fetched from AWS Secrets Manager. - Asset Upload: Files are uploaded to S3. Stable root files (
appconfig.json,index.html,sw.js) are uploaded last to act as the rollout cutover point. - CloudFront Invalidation: If a
DistroIdis found in the organization's secrets, a global/*invalidation is triggered.
Deployment Markers
The system uses "Deployment Markers" to track the progress of multi-environment deployments. These markers are updated in CircleCI to reflect the status (SUCCESS or FAILED) of specific environment targets.
Sources: scripts/deploy-markers.js:43-70
Environment Configuration
The appconfig.json file is the primary mechanism for environment-specific runtime configuration.
AppConfig Generation
The generate-appconfig.js script constructs this file by merging:
- AWS Secrets: Fetched from
customer/[stage]/[organization]. - Version Info: The git SHA or
CIRCLE_TAG. - Metadata: Deployment source (CI vs. Manual) and a Chicago-timezone timestamp.
Sources: scripts/generate-appconfig.js:90-105, scripts/generate-appconfig.js:31-45
Post-Deployment Validation
For specific stages like qa2, the system automatically dispatches End-to-End (E2E) tests upon successful deployment. This is achieved by triggering a GitHub repository dispatch event to the testing repository.
Sources: scripts/dispatch-qa2-e2e.js:40-48
Sources: scripts/dispatch-qa2-e2e.js:20-30
Summary
The CI/CD & Artifact Deployment system provides a robust, immutable pipeline for RoundingWell's frontend. By utilizing git tags for versioning, S3 for artifact storage, and CloudFormation for environment discovery, the system ensures that every deployment is traceable, verified, and consistent across different organizational environments. Key safety measures, such as ordered S3 uploads and mandatory checksum verification, minimize the risk of partial or corrupt rollouts.