Environments and Promotion

Modeling dev, staging, preview, and production with protected approvals, config overlays, and audit trails.

6 min readCI/CD & GitOpsPlatform

Environment Hierarchy

A typical environment hierarchy progresses from development to production. Each environment adds more validation, more scrutiny, and more stability requirements. The goal is to catch issues as early as possible, where they are cheapest to fix.

Environment	Purpose	Deploy Trigger	Approval
Development	Active development	Every push	None
Preview	PR validation	Pull request	None
Staging	Pre-production testing	Merge to main	Automatic
Production	Live users	After staging	Manual

GitHub Environments

GitHub multi-environment pipeline


name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment:
      name: staging
      url: https://staging.example.com
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh staging

  smoke-test:
    needs: deploy-staging
    runs-on: ubuntu-latest
    steps:
      - run: curl -f https://staging.example.com/health
      - run: npx playwright test --project=smoke

  deploy-production:
    needs: smoke-test
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://app.example.com
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh production

Each environment has its own protection rules configured in GitHub. Staging may auto-deploy on merge. Production requires manual approval from designated reviewers. The smoke test validates staging before production deployment.

GitLab Environments

GitLab CI environment configuration


deploy:staging:
  stage: deploy
  script:
    - ./deploy.sh staging
  environment:
    name: staging
    url: https://staging.example.com
    on_stop: stop:staging
    auto_stop_in: 1 week
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy:production:
  stage: deploy
  script:
    - ./deploy.sh production
  environment:
    name: production
    url: https://app.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
  allow_failure: false

stop:staging:
  stage: deploy
  script:
    - ./teardown.sh staging
  environment:
    name: staging
    action: stop
  when: manual

GitLab environments track deployment history and can auto-stop preview environments. The on_stop rule defines how to tear down the environment. auto_stop_in automatically removes environments after a specified time.

Config Overlays

Kustomize environment overlays


# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml

# overlays/staging/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patches:
  - target:
      kind: Deployment
      name: myapp
    patch: |
      - op: replace
        path: /spec/replicas
        value: 2
      - op: replace
        path: /spec/template/spec/containers/0/env/0/value
        value: staging
  - target:
      kind: ConfigMap
      name: myapp-config
    patch: |
      apiVersion: v1
      kind: ConfigMap
      metadata:
        name: myapp-config
      data:
        LOG_LEVEL: debug
        FEATURE_FLAG_URL: https://flags.staging.example.com

# overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patches:
  - target:
      kind: Deployment
      name: myapp
    patch: |
      - op: replace
        path: /spec/replicas
        value: 6
      - op: replace
        path: /spec/template/spec/containers/0/env/0/value
        value: production
  - target:
      kind: ConfigMap
      name: myapp-config
    patch: |
      apiVersion: v1
      kind: ConfigMap
      metadata:
        name: myapp-config
      data:
        LOG_LEVEL: warn
        FEATURE_FLAG_URL: https://flags.example.com

Kustomize overlays customize the base configuration per environment. Staging gets 2 replicas and debug logging. Production gets 6 replicas and warn-level logging. The same base manifests are deployed to all environments.

Promotion Gates

Automated tests — unit, integration, and end-to-end tests must pass before promotion.
Security scans — SAST, dependency, and container scans must have no critical findings.
Manual approval — production deployments require human sign-off from designated reviewers.
Canary verification — canary metrics must meet thresholds before full promotion.
Change advisory board — some organizations require CAB approval for production changes.

Audit Trails

Every deployment must be auditable

Record who deployed what, when, and to which environment. GitHub and GitLab automatically log deployment events. Combine these with your monitoring to create a complete audit trail. This is essential for compliance and incident investigation.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Stage 5 · Platform

Deployment Strategies