2. CI/CD Pipeline

Time to give your service its own deployment pipeline! This is the only manual CDK deploy you’ll ever do — after this, the pipeline takes care of itself.

What Is the Pipeline?

The pipeline is the automated system that takes your code from a git push all the way to a running service in AWS. You don’t deploy manually — the pipeline does it for you, every time.

HEMA uses a self-mutating CodePipeline — meaning the pipeline definition lives in the same repo as your code. If you change the pipeline, it updates itself. If you change your app, it deploys it. One push, everything handled.

How It Works (High Level)

The flow:

You push to main
Synth — installs deps, runs audit + lint + unit tests, builds the app, generates CloudFormation templates
Self-Mutate — if the pipeline definition changed, it updates itself first
Deploy — deploys your runtime (ECS Fargate container, load balancer, gateway routes)
E2E — runs Playwright tests against the live deployed environment

If any step fails, the pipeline stops. No broken code reaches production.

Two Stacks, One Repo

Your repo produces exactly two CloudFormation stacks:

Stack	Name	What It Contains	Who Deploys It
CI	`{project}-ci`	The pipeline itself (CodePipeline + CodeBuild)	You (once, manually)
Runtime	`{project}-rt`	Your running service (ECS + ALB + Gateway)	The pipeline (automatically)

Think of it this way: the CI stack is the factory, and the Runtime stack is the product. You build the factory once, and it produces the product on every push.

Deploy the Pipeline Stack

This is a one-time manual deployment from your local machine:

project="{service}-{component}" \
repo="{repository-name}" \
branch="main" \
environmentName="preprod" \
npx cdk deploy

Example for a PDP service:

project="omni-web-catalog-pdp" \
repo="omni-web-catalog-pdp" \
branch="main" \
environmentName="preprod" \
npx cdk deploy

After this, you never run cdk deploy manually again. Every push to main triggers the full pipeline.

Verify

Open CloudFormation Console → both stacks show CREATE_COMPLETE
Open CodePipeline Console → all stages green

Install Butler (Feature Sandboxes)

The main pipeline handles main branch deployments. But what about feature branches?

Butler gives you per-branch deployments. Push a feature branch → Butler creates an isolated stack with its own ECS service, ALB, and preview URL. Merge or delete the branch → Butler tears it down automatically.

This lets you test changes in a production-like environment before merging.

Deep Dive

For the full technical details (pipeline permissions, build environment, Playwright integration, garbage collection), see the CI/CD Pipeline Overview reference page.