CI CD Workflow & Ephemeral Environments

Overview

We follow a simple “one PR per ticket → merge to main” model with GitHub Actions powering several pipelines:

1. Schema Change Workflow
2. Full PR Pipeline
3. Tear-down on PR Close

---

1. Schema Change Workflow

This workflow runs only when schema.graphql is modified. It ensures API & client types stay in sync.

1. Trigger Condition

   • on: push or on: pull_request when schema.graphql changes.

2. Steps

   • Run npx graphql-codegen locally (CI installs dependencies then executes).
   • Generate:
     • React hooks (for frontend queries/mutations).
     • TypeScript interfaces (for backend resolvers).
   • If codegen output isn’t checked in, the job fails and asks contributor to regenerate.

3. Purpose

   • schema.graphql is the single source of truth for all data types.
   • Guarantees type safety between AppSync, Lambda resolvers, and React.

---

2. Full PR Pipeline

Runs on every PR against main, in this order:

2.1 Unit Tests

• Run all backend & frontend unit tests.
• Fail fast: If any test fails, pipeline stops here.

2.2 Deploy to Ephemeral Environment

Each PR branch name must follow our naming convention (e.g. feature/50-graphql-agenda-data)—used to provision isolated stacks.

1. Backend Stack (CDK)

   • Inputs: branch name, AWS credentials.
   • Resources:
     • DynamoDB tables
     • Lambda functions
     • AppSync API
     • Cognito User Pool
   • Outputs:
     • GraphQL endpoint URL
     • Cognito User Pool ID & domain

2. Inject Configuration into Frontend

   • Script writes a .env file in frontend/:

     REACT_APP_API_URL=<GraphQL URL>
     REACT_APP_COGNITO_USERPOOL_ID=<UserPool ID>
     REACT_APP_COGNITO_DOMAIN=<Cognito domain>
     

3. Frontend Stack (CDK)

   • Runs npm run build in frontend/
   • Deploys build to S3 & creates/updates CloudFront distribution
   • Invalidates CloudFront cache so the new version is served immediately.

4. Data Seeding (Test Only)

   • Populates DynamoDB with sample data
   • Creates a test user in Cognito User Pool

5. PR Comment

   • GitHub Actions posts:
     • Ephemeral environment URL
     • Cognito login link (if applicable)

2.3 End-to-End Tests (Playwright)

• Browsers: Chrome, Firefox, Safari, mobile Chrome & Safari.
• Flow Tested:
  1. Log in with test user
  2. Fetch user data via GraphQL
  3. Verify UI displays expected information
• Artifacts:
  • Screenshots & HTML report published to an external dashboard
  • PR comment with test status & report link (e.g. https://e2e.app.awscommunity.mx/...)

---

3. Tear-down on PR Close

When a PR is merged or closed:

1. Re-run the same CDK script in destroy mode.
2. Deletes:
   • Backend CloudFormation stack
   • Frontend CloudFormation stack
   • All associated AWS resources
3. Frees up environment to keep costs under control.

---

Branch & Naming Conventions

• Branch format:
  type/ISSUE_NUMBER-short-description
  example: feature/50-graphql-agenda-data

• Stack naming:
  Each CDK stack is prefixed by the branch name, e.g.:

  50-graphql-agenda-data-backend
  50-graphql-agenda-data-frontend
  

---

Benefits of This Workflow

• Type Safety on schema changes
• Fast Feedback via unit tests
• Isolated Test Environments per PR
• Automated E2E Validation
• Cost-Controlled Tear-down on branch cleanup