Managing Environments in AWS CI/CD Pipelines: Dev, Staging, and Prod

Simple explanation

Why environment management matters

Without explicit environment structure, code goes from a developer’s branch directly to production. A broken database migration, a misconfigured feature flag, or a slow query hits real users before anyone catches it. Environment promotion gives you two chances to find the problem first.

Environment separation also limits blast radius. When dev and production run in separate AWS accounts, an IAM policy mistake or a runaway script in dev cannot touch production resources. This is one of the most practical security guarantees in AWS at low cost.

How it works end to end

1. Commit — a developer merges a pull request to the main branch.
2. Build and test — CodeBuild runs the test suite, builds the Docker image, and pushes it to ECR tagged with the git commit SHA.
3. Deploy to dev — CodePipeline automatically deploys the image tag to the dev ECS cluster.
4. Validate dev — automated smoke tests run, or a developer verifies the feature manually.
5. Approve staging — a reviewer clicks Approve in the CodePipeline console. The same image tag deploys to the staging ECS cluster. Rejecting stops the pipeline here.
6. Validate staging — integration tests run against staging. The team confirms the release looks healthy.
7. Approve production — a second manual approval gate. This is non-negotiable for production workloads.
8. Deploy to production — the same image tag tested in dev and staging deploys to the production ECS cluster.

Dev vs staging vs production in AWS

Each environment has a distinct purpose and its infrastructure should reflect that. See Dev vs Staging vs Production in AWS for a detailed breakdown of how each differs in infrastructure sizing, data handling, and access controls. The short version:

• Dev — small instances, synthetic data, frequent deployments, no approval required. Cost should be low; uptime does not matter.
• Staging — production-equivalent instance types, anonymized or synthetic data at production-like volume, deployments gated by manual approval. Uptime matters during pre-release testing windows.
• Production — full infrastructure, real data, manual approval required, alerting enabled, and a documented rollback procedure before every deployment.

Separate AWS accounts vs separate VPCs

You have two options for isolating environments: separate AWS accounts per environment, or separate VPCs within a single account. Both work, but they offer different levels of isolation.

Recommended architecture by team size and risk level

The right time to add approval gates and account separation is before you have production users, not after. Retrofitting these controls into a pipeline already running without them is harder than building them in from the start.

Example CodePipeline flow for multi-environment promotion

A CodePipeline covering three environments has at minimum: a source stage, a build stage, a dev deployment, an approval before staging, a staging deployment, an approval before production, and a production deployment. For ECS-based workloads, the deployment stages use the ECS action type.

# cloudformation/pipeline.yaml (simplified)
Stages:
  - Name: Source
    Actions:
      - Name: GitHub
        ActionTypeId:
          Category: Source
          Owner: ThirdParty
          Provider: GitHub

  - Name: Build
    Actions:
      - Name: BuildAndTest
        ActionTypeId:
          Category: Build
          Owner: AWS
          Provider: CodeBuild
        # Builds image tagged with commit SHA, runs tests, pushes to ECR

  - Name: DeployDev
    Actions:
      - Name: Deploy
        ActionTypeId:
          Category: Deploy
          Owner: AWS
          Provider: ECS
        Configuration:
          ClusterName: dev-cluster
          ServiceName: my-app-dev

  - Name: ApproveStaging
    Actions:
      - Name: ManualApproval
        ActionTypeId:
          Category: Approval
          Owner: AWS
          Provider: Manual
        Configuration:
          NotificationArn: arn:aws:sns:us-east-1:123456789012:pipeline-approvals

  - Name: DeployStaging
    Actions:
      - Name: Deploy
        ActionTypeId:
          Category: Deploy
          Owner: AWS
          Provider: ECS
        Configuration:
          ClusterName: staging-cluster
          ServiceName: my-app-staging

  - Name: ApproveProduction
    Actions:
      - Name: ManualApproval
        ActionTypeId:
          Category: Approval
          Owner: AWS
          Provider: Manual
        Configuration:
          NotificationArn: arn:aws:sns:us-east-1:123456789012:pipeline-approvals

  - Name: DeployProduction
    Actions:
      - Name: Deploy
        ActionTypeId:
          Category: Deploy
          Owner: AWS
          Provider: ECS
        Configuration:
          ClusterName: prod-cluster
          ServiceName: my-app-prod

Each approval stage sends an SNS notification to the team. A reviewer logs into the console, verifies the previous environment looks healthy, and clicks Approve or Reject. Rejecting leaves the next environment unchanged.

For the production stage, consider pairing this with blue-green deployments or canary releases so traffic shifts gradually. Both strategies make it significantly easier to roll back if something goes wrong after cutover.

Managing environment-specific configuration

Each environment needs different values: different database hostnames, different API endpoints, different feature flags. Store them in AWS Systems Manager Parameter Store, organized by environment prefix:

aws ssm put-parameter \
  --name "/dev/database/host" \
  --value "dev-db.cluster-abc123.us-east-1.rds.amazonaws.com" \
  --type String

aws ssm put-parameter \
  --name "/staging/database/host" \
  --value "staging-db.cluster-def456.us-east-1.rds.amazonaws.com" \
  --type String

aws ssm put-parameter \
  --name "/prod/database/host" \
  --value "prod-db.cluster-ghi789.us-east-1.rds.amazonaws.com" \
  --type SecureString

The application reads its own parameter at startup using an environment prefix injected by the ECS task definition. The pipeline does not carry configuration values — it only deploys the image tag. For credentials and API keys specifically, see Managing Secrets in CI/CD Pipelines on AWS.

# Application reads its own config at startup
import boto3, os

env = os.environ.get("APP_ENV", "dev")  # Injected by ECS task definition
ssm = boto3.client("ssm")
db_host = ssm.get_parameter(Name=f"/{env}/database/host")["Parameter"]["Value"]

Adding a new environment means adding a new Parameter Store prefix and a new pipeline stage. No changes to application code required.

Promoting the same image tag or artifact

Build once. Promote the same artifact. This is the single most important rule of multi-environment CI/CD.

Rebuilding the Docker image per environment is a common mistake. Even with identical source code, each rebuild can produce a different image: packages may resolve to newer patch versions, build layer caches differ, timestamps change. What staging tested is no longer byte-for-byte identical to what reaches production.

In the build stage, tag the image with the git commit SHA and push it to ECR. Every deploy stage uses that same tag. The image is immutable.

# Build stage — tag with commit SHA, push once
IMAGE_TAG=$CODEBUILD_RESOLVED_SOURCE_VERSION
docker build -t $ECR_REPO:$IMAGE_TAG .
docker push $ECR_REPO:$IMAGE_TAG

# Dev, staging, and production all reference the same IMAGE_TAG
# Passed between stages as a CodePipeline output artifact

Pass the image tag as a CodePipeline output artifact from the build stage. Each deploy stage reads it as an input artifact. The tag never changes as it moves through the pipeline.

IAM roles and cross-account deployment

The pipeline runs under a pipeline execution role in the tools account. That role should not have direct permissions to modify dev, staging, or production resources. Instead, define a deployment role in each target account and configure the pipeline to assume it per stage.

# Deployment role in the target account (dev, staging, or prod)
# Trusted by the pipeline execution role in the tools account
aws iam create-role \
  --role-name CodePipelineDeployRole \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::TOOLS_ACCOUNT_ID:role/CodePipelineExecutionRole"
      },
      "Action": "sts:AssumeRole"
    }]
  }'

When deploying with AWS CodeDeploy, each environment’s CodeDeploy service role is scoped to that account only. The secure CI/CD pipelines guide covers the full role structure and least-privilege policy design in detail.

When to use this setup

• Early-stage / small teams: A lighter version — one account, two environments, one approval — is acceptable while you have no compliance obligations and low production risk. Plan to add separate accounts when you have paying customers.
• Growing teams: Add a staging account, enforce approval gates for staging and production, and migrate environment config to Parameter Store per account. This is where informal processes break down and explicit structure pays off. Infrastructure as Code keeps environments consistent as the team grows.
• Production-critical workloads: Full separate accounts, SCPs at the OU level, two approvers before production, all deployments logged to CloudTrail, and a documented rollback procedure before every release. You need to be able to reproduce any environment from source.