CI/CD with GitHub Actions

Relevant source files

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

• README.md
• package.json
• backend/package.json
• infrastructure/aws/cdk/package.json
• infrastructure/aws/cdk/lib/atlasclean-stack.ts
• infrastructure/terraform/main.tf

AtlasCleanAI Enterprise employs GitHub Actions to automate code validation, infrastructure provisioning, and application deployments. The automation strategy ensures that backend code, Flutter packages, and cloud infrastructure meet quality standards before reaching production environments.

The system uses environment isolation, staging validation, and gated production releases to maintain platform stability. Deployment workflows integrate with AWS using OpenID Connect (OIDC) to securely assume IAM roles without long-lived credentials.
Sources: README.md:92-106, README.md:143-150

Pipeline Architecture

The automation architecture consists of three distinct workflows that process code from the monorepo to AWS environments.

This diagram illustrates the progression from initial code validation to gated production deployments.
Sources: README.md:92-101, README.md:154-156

Workflow Definitions

The platform categorizes automation into functional pipelines that handle different stages of the software development lifecycle.

CI Pipeline

The CI pipeline performs quality checks on every pull request and push to the main branch. It validates the backend API, shared Flutter packages, and repository security.

• Backend Validation: Executes npm test and eslint to ensure code quality and logic correctness.
• Flutter Validation: Checks the atlas_design_system and atlas_api_client packages for compilation and linting errors.
• Security Scan: Scans the repository for vulnerabilities and exposed secrets.
  Sources: README.md:95-97, backend/package.json:7-13, packages/atlas_design_system/pubspec.yaml

Deployment Pipelines

The deployment workflows manage infrastructure-as-code (IaC) and containerized application updates.

1. Deploy Staging: Automatically builds and deploys changes to the staging AWS account for validation.
2. Deploy Production: Requires manual approval via GitHub Environments before deploying to the production AWS account.
   Sources: README.md:98-101, infrastructure/aws/cdk/package.json:6-9

Infrastructure Automation Options

Teams choose between two IaC implementations within the GitHub Actions workflows.

AWS CDK Workflow

The CDK workflow uses TypeScript to define resources. GitHub Actions executes specific npm scripts to manage these stacks.

• Synthesis: npm run synth generates AWS CloudFormation templates.
• Staging Deployment: npm run deploy:staging targets the AtlasClean-staging stack.
• Production Deployment: npm run deploy:production targets the AtlasClean-production stack.
  Sources: infrastructure/aws/cdk/package.json:6-9, infrastructure/aws/cdk/lib/atlasclean-stack.ts:18-20

Terraform Workflow

The Terraform workflow provides provider-agnostic conventions for infrastructure management.

• Initialization: terraform init prepares the working directory.
• Planning: terraform plan generates execution plans for review.
• Application: terraform apply executes the infrastructure changes.
  Sources: README.md:129-133, infrastructure/terraform/main.tf:1-12

Configuration and Secrets

GitHub Actions requires specific secrets and variables to interact with AWS and provision the environment.

Name	Type	Purpose
AWS_ROLE_TO_ASSUME	Secret/Variable	IAM role assumed via OIDC for AWS access
AWS_REGION	Variable	The target AWS region (e.g., us-east-1)
CDK_DEFAULT_ACCOUNT	Variable	AWS Account ID for CDK operations
ATLAS_CERTIFICATE_ARN	Secret	ACM certificate ARN for HTTPS termination
JWT_SECRET	Secret	Signing key for application access tokens
DB_PASSWORD	Secret	Master password for the RDS PostgreSQL instance

Sources: README.md:106-114, infrastructure/terraform/variables.tf:98-115, infrastructure/aws/cdk/lib/atlasclean-stack.ts:60-70

Deployment Sequence

When a deployment workflow triggers, it follows a strict sequence to ensure the environment is ready for the application container.

The sequence shows how GitHub Actions authenticates with AWS and coordinates the container rollout.
Sources: README.md:106-114, infrastructure/aws/cdk/lib/atlasclean-stack.ts:182-205, infrastructure/terraform/main.tf:455-465

Security and Observability in CI/CD

The pipelines enforce production security standards:

• Immutable Deployments: The system uses ECR image tags rather than patching live containers.
• Least Privilege: GitHub Actions assumes specific IAM roles via OIDC.
• Isolation: Resources are deployed into distinct network tiers (public, application, and data subnets).
• Health Validation: Deployments only complete if the /health endpoint returns a 200 OK status.
  Sources: README.md:143-156, infrastructure/aws/cdk/lib/atlasclean-stack.ts:25-50, backend/src/app.ts:208-217

CI/CD automation in AtlasCleanAI Enterprise provides a repeatable, secure, and audited path for delivering AI-powered cleaning management features from code to the cloud.