Release Management & Scripts
Relevant source files
The following files were used as context for generating this wiki page:
The Release Management system in the app-frontend repository is a collection of Node.js scripts and automation workflows designed to handle the lifecycle of the application from versioning and tagging to artifact publication and multi-environment deployment. This system ensures that releases are immutable, traceable, and consistent across different environments.
The automation is primarily driven by scripts in the scripts/ directory, which interact with Git for version control and AWS for infrastructure management (S3, CloudFront, CloudFormation, and Secrets Manager). Releases are strictly tag-based, and the deployment process consumes artifacts generated from these tags.
Sources: README.md:14-16, scripts/AGENTS.md:5-7
Release Tagging and Versioning
Releases are initiated by creating an annotated Git tag. The system enforces strict rules on where releases can originate and how tags are formatted to maintain a linear and predictable release history.
Release Constraints and Validation
To ensure stability, the release.js script performs several pre-flight checks before a tag is created:
- Allowed Branches: Releases can only be created from the
developbranch or branches matching therelease/*pattern. - Clean Working Tree: No uncommitted changes are allowed.
- Upstream Sync: The local HEAD must match the upstream branch.
- Reachability: The commit to be tagged must be reachable from
origin/developor anorigin/release/*branch. - Immutability: Tags are immutable; the script fails if the tag already exists locally or on the remote origin.
Sources: scripts/release.js:58-154, README.md:18-35
Tag Format
Tags follow the format vYYMMDD.N, where:
YYMMDDis the UTC date of creation.Nis an incremental sequence number starting at 1 for that specific date.
Sources: scripts/release.js:167-184, README.md:27-29
Release Flow Logic
The following diagram illustrates the logical flow of the release.js script:
The annotated tag includes a message containing the branch name, commit SHA, and a UTC timestamp.
Sources: scripts/release.js:199-253
Artifact Management
Once a release tag is pushed, CircleCI generates a distribution artifact (typically a .tar.gz file) and publishes it to a centralized storage location.
Publication (publish-artifact.js)
The publication script ensures that artifacts and their checksums are stored in S3 under a keyed prefix. It enforces immutability by blocking uploads if a file already exists for a specific tag.
| Parameter | Default / Source | Description |
|---|---|---|
bucket | rw-frontend-artifacts-dev | The S3 bucket for artifact storage |
prefix | app-frontend | S3 key prefix |
tag | ARTIFACT_TAG (env) | The release tag version |
artifact | /tmp/dist.tar.gz | Path to the local distribution archive |
checksum | ${artifact}.sha256 | Path to the SHA256 checksum file |
Sources: scripts/publish-artifact.js:9-30, scripts/publish-artifact.js:80-97
Deployment Infrastructure
Deployment is the process of taking a published artifact, generating environment-specific configurations, and uploading the files to the respective S3 website buckets.
Deployment Targets and Discovery
The deploy.js script dynamically discovers deployment targets using AWS CloudFormation. It filters stacks based on tags for stage (e.g., prod, qa) and optionally a specific organization.
Application Configuration (generate-appconfig.js)
Each deployment generates a unique appconfig.json file. This file contains metadata about the release and organization-specific secrets fetched from AWS Secrets Manager.
| Metadata Field | Source |
|---|---|
version | DEPLOY_TARGET_VERSION or Git short SHA |
deploymentTime | ISO8601 timestamp (Chicago timezone) |
deploymentSource | "Manual" or "Continuous Integration" |
secrets | AWS Secrets Manager (path: customer/<stage>/<org>) |
Sources: scripts/generate-appconfig.js:33-46, scripts/generate-appconfig.js:77-101
Deployment Execution Flow
The deployment process involves a specific upload order to ensure zero-downtime or consistent rollouts.
"Rollout cutover points" like index.html and appconfig.json are uploaded last to ensure the new version is fully staged before being served.
Sources: scripts/deploy.js:142-205, scripts/deploy.js:292-316
Deployment Markers and Monitoring
Deployment markers are used to track the progress and status of releases across different environments in the CI/CD pipeline.
Marker Lifecycle (deploy-markers.js)
- Plan: Creates a "planned" status marker for all target environments.
- Update: Updates the marker to
SUCCESSorFAILEDbased on the outcome of the deployment script.
Markers use a slugified name format: deploy-<env-slug>-<version>. For multi-organization stages, markers are created for both the specific organization (e.g., qa:qa2) and a wildcard representation (e.g., qa:*).
Sources: scripts/deploy-markers.js:7-12, scripts/deploy-markers.js:91-137, scripts/deploy.js:364-375
Summary of Release Commands
Available via npm run:
| Command | Script | Description |
|---|---|---|
release | release.js | Validates environment and creates/pushes a new release tag. |
release:dry-run | release.js --dry-run | Runs all release validations without creating the tag. |
deploy | deploy.js | Deploys build to S3/CloudFront for a specific stage. |
artifact:publish | publish-artifact.js | Uploads the distribution archive to S3. |
Sources: package.json:69-71, README.md:20-25
Release management and scripting in this repository provide a robust, automated framework for moving code from development to production. By leveraging Git tags as immutable version identifiers and automating the discovery of AWS infrastructure via CloudFormation tags, the project maintains a scalable deployment architecture that supports multiple organizations and stages with minimal manual intervention.