Skip to content

pwa-deployment.md

Latest commit

 

History

History
136 lines (119 loc) · 5.92 KB

pwa-deployment.md

File metadata and controls

136 lines (119 loc) · 5.92 KB

PWA Deployment

A comprehensive Progressive Web Application deployment workflow supporting S3 static hosting with CloudFront CDN, multi-environment deployments, branch-based previews, and multi-brand configurations.

Features

  • Multi-environment support: staging, production, and preview environments
  • Branch-based previews: Automatic preview deployments for pull requests
  • Dual cache strategies: Immutable caching for static assets, revalidation for HTML
  • CloudFront integration: Automatic cache invalidation with configurable paths
  • Multi-brand deployment: Parallel deployment support for multiple brands
  • Node.js 16-22 support: Compatible with Yarn and npm package managers
  • Manual production gates: Environment-based deployment protection
  • Comprehensive caching: Build artifact optimisation and cleanup
  • Automatic backporting: Optional PR creation to backport changes to staging branch

GitHub Environment Variables and Secrets

Environment-specific values are read directly from the GitHub Environment (set via github-environment), rather than being passed as workflow inputs. Configure the following on each environment:

Name Type Required Description
S3_BUCKET variable ✅ S3 bucket name for deployment
CLOUDFRONT_DISTRIBUTION_ID variable ✅ CloudFront distribution ID for cache invalidation
AWS_REGION variable ❌ AWS region (falls back to aws-region input)
Static credentials
AWS_ACCESS_KEY_ID variable ✅ AWS access key ID (required if not using OIDC)
AWS_SECRET_ACCESS_KEY secret ✅ AWS secret access key (required if not using OIDC)
OIDC
AWS_ROLE_ARN variable ✅ IAM role ARN to assume via OIDC (alternative to static credentials)

Either AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY or AWS_ROLE_ARN must be configured. The workflow detects which to use automatically.

Note: Backporting only occurs when deploying from production, main, or master branches. Deployments from other branches are skipped.

Inputs

Name Required Type Default Description
Environment Configuration
github-environment ✅ string GitHub Environment name for secrets/variables (e.g. Staging, Production)
AWS Configuration
aws-region ❌ string ap-southeast-2 AWS region fallback (overridden by AWS_REGION environment variable if set)
role-session-name ❌ string AWS role session name for OIDC (default: {repo}-{short-sha}-{run-number})
Build Configuration
package-manager ❌ string yarn Node package manager (yarn/npm)
is-yarn-classic ❌ boolean false Use Yarn Classic (pre-Berry) instead of modern Yarn
build-command ❌ string build Build command to execute
build-directory ❌ string dist Directory containing built assets to deploy
Cache Strategy Configuration
cache-strategy ❌ string immutable Cache strategy for assets (immutable/no-cache)
Preview Environment Configuration
preview-mode ❌ boolean false Enable preview mode for PR-based deployments
preview-base-url ❌ string Base URL for preview deployments
Multi-brand Configuration
brand-config ❌ string JSON configuration for multi-brand deployments
Advanced Configuration
cloudfront-invalidation-paths ❌ string ["/*"] CloudFront invalidation paths (JSON array)
extra-sync-args ❌ string Additional AWS S3 sync arguments
Debug and Control
debug ❌ boolean false Enable verbose logging and debug output
Backport Configuration
create-backport-pr ❌ boolean false Create a backport PR after deployment
backport-target-branch ❌ string staging Target branch for backport PR

Outputs

Name Description
deployment-url URL of the deployed application
preview-url Preview URL for PR deployments

Example Usage

Basic Deployment (Static Credentials):

jobs:
  deploy-staging:
    uses: aligent/workflows/.github/workflows/pwa-deployment.yml@main
    with:
      github-environment: Staging
    secrets: inherit

The Staging GitHub Environment must have S3_BUCKET, CLOUDFRONT_DISTRIBUTION_ID, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY configured.

Basic Deployment (OIDC):

jobs:
  deploy-production:
    uses: aligent/workflows/.github/workflows/pwa-deployment.yml@main
    with:
      github-environment: Production
    secrets: inherit

The Production GitHub Environment must have S3_BUCKET, CLOUDFRONT_DISTRIBUTION_ID, and AWS_ROLE_ARN configured.

Preview Environment for Pull Requests:

jobs:
  deploy-preview:
    if: github.event_name == 'pull_request'
    uses: aligent/workflows/.github/workflows/pwa-deployment.yml@main
    with:
      github-environment: Preview
      preview-mode: true
      preview-base-url: https://preview.example.com
      cache-strategy: no-cache
    secrets: inherit

Multi-brand Deployment:

jobs:
  deploy-multi-brand:
    uses: aligent/workflows/.github/workflows/pwa-deployment.yml@main
    with:
      github-environment: Production
      brand-config: '{"brand":["brand-a","brand-b","brand-c"]}'
      build-command: build:brands
    secrets: inherit

Custom Build Configuration:

jobs:
  deploy-custom:
    uses: aligent/workflows/.github/workflows/pwa-deployment.yml@main
    with:
      github-environment: Staging
      package-manager: npm
      build-command: build:staging
      build-directory: build
      cloudfront-invalidation-paths: '["/*", "/api/*"]'
      extra-sync-args: --exclude "*.map"
      debug: true
    secrets: inherit