Triggering Workflows

Once the ECS application setup is complete, validate the CI/CD workflows by triggering deployments through pull requests and releases. This guide explains what happens at each stage and where to monitor your deployments.

Deployment Environments

Each environment maps to a specific ECS cluster and GitHub Environment:

Environment	ECS Cluster	GitHub Environment	Trigger
Preview	dev cluster	preview	PR with deploy label
Dev	dev cluster	dev	Push to main
Staging	staging cluster	staging	Publish release
Production	prod cluster	prod	After staging (with approval)

Flexible Environment Targeting

Each workflow explicitly specifies which Atmos stack to deploy (e.g., atmos terraform deploy app -s staging). The stack configuration defines which ECS cluster and account to target. This approach makes environment selection fully customizable — you can add new environments, change cluster mappings, or adjust deployment targets without modifying the workflow logic.

Image Tagging Strategy

The same Docker image flows through all environments — no rebuilding between stages. This ensures what you test is exactly what you deploy to production.

How it works:

1. On PR/main push: CI builds the image once and pushes it with a sha-<commit> tag (e.g., sha-a1b2c3d). Pushes to main also tag as latest.

2. Preview & Dev: Deploy using the sha-<commit> tag. The exact commit being deployed is always traceable.

3. On release: The existing image is promoted (re-tagged) with the release version (e.g., v1.2.3). No rebuild occurs — the identical image bytes are tagged with a new name.

4. Staging & Production: Deploy using the version tag. Both environments run the exact same image that was tested in dev.

Why This Matters

Rebuilding images between environments risks subtle differences (updated dependencies, timing issues, etc.). By promoting the same image, you guarantee that staging and production run identical code to what was tested in dev.

1 Deploy a Preview Environment

Preview environments let you test changes before merging to main. They deploy to the dev cluster with isolated resources.

To trigger a preview deployment:

• Create a feature branch and push changes
• Open a pull request targeting main
• Add the deploy label to the PR

CI steps:

1. Build — Builds the Docker image
2. Push — Pushes the image to your container registry (ECR by default) with tag sha-<commit>

CD steps:

1. Deploy — Runs Atmos to deploy the app component. The component configuration specifies the Docker image to pull, using the !env function to read the image from the environment variable set by CI, with a fallback default.

Where to see your preview environment:

• GitHub UI: Click the "Deployments" section in your PR, or look for the environment link in the workflow summary
• AWS Console: Navigate to ECS → Clusters → dev cluster → Services → look for service with PR number suffix
• Application URL: The workflow outputs the URL — check the "Deploy" job summary

2 Cleanup Preview Environments

Preview environments are automatically destroyed when:

• The PR is closed or merged
• The deploy label is removed

The preview-cleanup.yml workflow runs atmos terraform destroy app -s preview to remove all resources.

3 Deploy to Dev

Merging to main automatically deploys to the dev environment.

To trigger a dev deployment:

• Merge your PR to main (or push directly to main)

CI steps:

1. Build — Builds the Docker image
2. Push — Pushes the image to your container registry (ECR by default) with tag sha-<commit>

CD steps:

1. Deploy — Runs Atmos to deploy the app component to the dev stack
2. Release — Creates a draft GitHub Release for promotion to staging/production

Where to see your dev deployment:

• GitHub UI: Go to Actions → "Main Branch" workflow → click the dev environment link
• AWS Console: ECS → Clusters → dev cluster → Services → your app service
• Application URL: Check the "Deploy" job output for the URL

4 Deploy to Staging

Staging deployments are triggered by publishing a GitHub Release.

To trigger a staging deployment:

• Go to GitHub → Releases → find the draft release created by the main branch workflow
• Edit the release — add release notes if desired
• Click "Publish release"

CI steps:

1. Promote — Tags the existing Docker image with the release version (e.g., v1.2.3). No rebuild occurs — the same tested image is promoted.

CD steps:

1. Deploy — Runs Atmos to deploy the app component to the staging stack

Where to see your staging deployment:

• GitHub UI: Actions → "Release" workflow → click the staging environment link
• AWS Console: ECS → Clusters → staging cluster → Services → your app service
• Application URL: Check the "deploy / staging" job output

5 Deploy to Production

Production deployment happens automatically after staging, with an optional approval gate.

CD steps:

1. Approval — Waits for manual approval (if configured)
2. Deploy — Runs Atmos to deploy the app component to the prod stack

Where to see your production deployment:

• GitHub UI: Actions → "Release" workflow → click the prod environment link
• AWS Console: ECS → Clusters → prod cluster → Services → your app service
• Application URL: Check the "deploy / production" job output

Configuring approval gates:

To require manual approval before production deployments:

1. Go to your repository → Settings → Environments
2. Click on the prod environment (create it if it doesn't exist)
3. Check "Required reviewers"
4. Add the users or teams who can approve deployments
5. Optionally set a "Wait timer" to add a delay before deployment

GitHub Enterprise

Approval gates require GitHub Enterprise or a public repository. For GitHub Team plans, consider using a separate workflow with manual trigger (workflow_dispatch) for production.

Monitoring Deployments

GitHub Actions

All deployment status is visible in the GitHub Actions tab:

• Workflow runs: See all triggered workflows and their status
• Environment deployments: Each environment shows deployment history
• Job logs: Click into any job to see detailed logs including Terraform output

AWS Console

Monitor your ECS services directly:

1. Navigate to ECS → Clusters → select your cluster
2. Click on your Service
3. View the Deployments tab to see rollout status
4. Check Tasks tab to see running containers
5. View Logs tab for application logs (if configured with CloudWatch)

Application Health

After deployment, verify your application:

• Access the application URL from the workflow output
• Check health endpoint (typically /health or /healthz)
• Review CloudWatch logs for any startup errors
• Monitor CloudWatch metrics for CPU/memory usage

Troubleshooting

Issue	Solution
Preview not deploying	Verify the deploy label is added to the PR
"No changes" in Terraform	The image tag might be the same — push a new commit
Deployment timeout	Check ECS service events for task startup failures
Image not found	Verify ECR permissions and image tag exists
Auth errors	Check IAM role trust policy includes your repository

Next Steps

• Review the ECS with Atmos overview for architecture details
• Learn about GitHub OIDC with AWS for authentication
• Explore ECS cluster setup for platform infrastructure