CI/CD Pipeline

Relevant source files

The following files were used as context for generating this wiki page:

• terraform/github-actions-deployment/main.tf
• e2e/helpers.ts
• frontend/package.json
• frontend/playwright-ct.config.ts
• e2e/tests/task/task-management.spec.ts
• terraform/infrastructure/main.tf

The CI/CD pipeline for the Collimator project automates the process of testing, building, and deploying the application to the AWS cloud infrastructure. It leverages GitHub Actions for orchestration, Terraform for infrastructure and deployment configuration, and a comprehensive testing suite including Jest and Playwright to ensure code quality and stability.

The pipeline is designed to provide a consistent and reliable path from code commit to production. Continuous Integration (CI) focuses on running a variety of automated tests and builds for the frontend and backend applications. Continuous Deployment (CD) is handled through a secure integration between GitHub Actions and AWS, allowing for automated updates to the running services and static assets.

Continuous Integration (CI)

The CI process is triggered on code changes and is responsible for validating the integrity of the application through automated testing and builds.

Testing Strategy

The project employs a multi-layered testing strategy to cover different aspects of the application. The main test command yarn test orchestrates the execution of both Jest and Playwright tests.

Sources: frontend/package.json:14

Unit and Component Tests

• Jest: Used for unit testing. The command yarn test:jest executes these tests. A coverage report can be generated with yarn test:jest:cov.
• Playwright Component Tests: Used for testing React components in isolation. The command yarn test:ct runs these tests using the configuration defined in playwright-ct.config.ts. This setup uses Vite and includes the vite-plugin-istanbul for instrumenting code to generate coverage reports.

Sources: frontend/package.json:18-24, frontend/playwright-ct.config.ts:41-49

End-to-End (E2E) Tests

E2E tests validate complete user flows across the entire application stack. These tests are managed by Playwright and are configured to run in a fully isolated environment for each test worker.

The following diagram illustrates the E2E test environment setup process.

Key features of the E2E test setup:

• Database Isolation: A new database is created for each worker by cloning a template database. This ensures that tests run in parallel do not interfere with each other. The database is dropped after the tests complete.
• Full Stack Environment: The backend (NestJS) and frontend (Next.js) applications are started as separate processes on dynamically allocated ports.
• Database Seeding: The _databaseSeed fixture in the test helper ensures that the database is reset between different test files, providing a clean state for each suite.
• Test Example: Tests like task-management.spec.ts use page models (TaskListPageModel) to interact with the UI, performing actions such as creating, editing, and deleting tasks, and asserting the expected outcomes.

Sources: e2e/helpers.ts:70-176, e2e/tests/task/task-management.spec.ts

Build Process

The CI pipeline also includes steps to build the application artifacts.

• Frontend: The Next.js frontend is built using the yarn build command, which executes next build.
• Backend: The NestJS backend has start:prod scripts, indicating a production build process is available.

Sources: frontend/package.json:8, backend/README.md:32

CI Scripts Summary

The following table summarizes the key scripts defined in frontend/package.json that are used in the CI pipeline.

Script	Description
test	Runs both Jest and Playwright tests.
test:jest	Executes Jest unit tests.
test:ct	Runs Playwright component tests and generates a coverage report.
test:cov	Runs a full test suite (Jest and Playwright) with code coverage enabled.
build	Compiles the Next.js frontend for production.
lint	Runs the Next.js linter.

Sources: frontend/package.json:7-19

Continuous Deployment (CD)

The CD process is managed by Terraform and executed via GitHub Actions. It automates the deployment of new application versions to the AWS infrastructure.

GitHub Actions Integration with AWS

A secure, passwordless connection between GitHub Actions and AWS is established using OpenID Connect (OIDC).

The following diagram shows the authentication flow.

• An aws_iam_openid_connect_provider is configured for https://token.actions.githubusercontent.com.
• An IAM role is created with a trust policy that allows it to be assumed by a specific GitHub repository (repo:${var.github_account_name}/${var.github_repo_name}:*).

Sources: terraform/github-actions-deployment/main.tf:2-33

Deployment Permissions

The IAM role assumed by GitHub Actions is granted a specific set of permissions required for deployment. These permissions are defined in the ci-deploy-policy and are limited to only what is necessary.

Service	Actions	Resources	Purpose
ECR	CompleteLayerUpload, UploadLayerPart, InitiateLayerUpload, BatchCheckLayerAvailability, PutImage, BatchGetImage	ECR Repository ARNs	Push new backend container images.
ECR	GetAuthorizationToken	*	Authenticate the Docker client to ECR.
ECS	UpdateService	ECS Service ARNs	Trigger a new deployment of the backend service on Fargate.
S3	ListBucket	S3 Bucket ARNs	List contents of frontend buckets.
S3	*Object, ListMultipartUploadParts, GetObjectVersion, GetObjectTagging	Objects within S3 Buckets	Upload, update, and delete frontend static assets.

Sources: terraform/github-actions-deployment/main.tf:45-103

Target Infrastructure

The CD pipeline deploys artifacts to the infrastructure defined in terraform/infrastructure/main.tf.

• Frontend: The frontend and scratchapp applications are deployed as static websites to S3 buckets.
• Backend: The backend application is deployed as a containerized service on AWS ECS Fargate.

Sources: terraform/infrastructure/main.tf:16-29, 56-74