Implementation:Mage ai Mage ai GitHub Actions ECS Deploy

Knowledge Sources	Mage AI Mage Deployment Docs
Domains	Deployment, CI_CD, AWS
Last Updated	2026-02-09 00:00 GMT

Overview

GitHub Actions workflow template for building a Docker image and deploying Mage to a single AWS ECS environment.

Description

This GitHub Actions workflow template named "Deploy to Amazon ECS" triggers on pushes to the master branch and automates the full build-and-deploy pipeline to AWS Elastic Container Service. The workflow runs a single deploy job on ubuntu-latest targeting the production environment. It executes six sequential steps: (1) checks out the repository using actions/checkout@v5, (2) configures AWS credentials using the aws-actions/configure-aws-credentials action with AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from GitHub secrets, (3) logs in to Amazon ECR using aws-actions/amazon-ecr-login, (4) builds a Docker image tagged with the git commit SHA and pushes it to ECR, (5) downloads the current ECS task definition using aws ecs describe-task-definition and renders the new image ID into it using aws-actions/amazon-ecs-render-task-definition@v1, and (6) deploys the updated task definition to ECS using aws-actions/amazon-ecs-deploy-task-definition@v1 with wait-for-service-stability: true. Six environment variables must be configured at the workflow level: AWS_REGION, ECR_REPOSITORY, ECS_SERVICE, ECS_CLUSTER, ECS_TASK_DEFINITION, and CONTAINER_NAME.

Usage

Copy this template into your repository's .github/workflows/ directory. Replace the placeholder environment variable values (MY_AWS_REGION, MY_ECR_REPOSITORY, etc.) with your actual AWS resource names. Add AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as GitHub repository secrets.

Code Reference

Source Location

• Repository: mage-ai
• File: templates/github_actions/build_and_deploy_to_aws_ecs.yml
• Lines: 1-71

Signature

name: Deploy to Amazon ECS

on:
  push:
    branches:
      - master

env:
  AWS_REGION: MY_AWS_REGION
  ECR_REPOSITORY: MY_ECR_REPOSITORY
  ECS_SERVICE: MY_ECS_SERVICE
  ECS_CLUSTER: MY_ECS_CLUSTER
  ECS_TASK_DEFINITION: MY_ECS_TASK_DEFINITION
  CONTAINER_NAME: MY_CONTAINER_NAME

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Checkout
      - name: Configure AWS credentials
      - name: Login to Amazon ECR
      - name: Build, tag, and push image to Amazon ECR
      - name: Download task definition
      - name: Fill in the new image ID in the Amazon ECS task definition
      - name: Deploy Amazon ECS task definition

Import

# Template file - copy to your project's GitHub Actions workflow directory
# cp templates/github_actions/build_and_deploy_to_aws_ecs.yml \
#    .github/workflows/deploy_to_ecs.yml

I/O Contract

Inputs

Name	Type	Required	Description
AWS_REGION	workflow env var	Yes	AWS region for ECR and ECS (e.g., us-west-1)
ECR_REPOSITORY	workflow env var	Yes	Amazon ECR repository name
ECS_SERVICE	workflow env var	Yes	Amazon ECS service name to update
ECS_CLUSTER	workflow env var	Yes	Amazon ECS cluster name
ECS_TASK_DEFINITION	workflow env var	Yes	ECS task definition family name (used to fetch the current definition)
CONTAINER_NAME	workflow env var	Yes	Name of the container in the task definition's containerDefinitions section
AWS_ACCESS_KEY_ID	GitHub secret	Yes	AWS IAM access key ID with ECR and ECS permissions
AWS_SECRET_ACCESS_KEY	GitHub secret	Yes	AWS IAM secret access key

Outputs

Name	Type	Description
Docker image	ECR image	Docker image tagged with the git commit SHA pushed to Amazon ECR
Task definition	ECS task definition revision	New task definition revision with the updated container image
Service update	ECS service deployment	ECS service updated with the new task definition, confirmed stable

Workflow Steps

1. Checkout -- Clones the repository using actions/checkout@v5
2. Configure AWS credentials -- Sets up AWS credentials from GitHub secrets using aws-actions/configure-aws-credentials
3. Login to Amazon ECR -- Authenticates Docker to the ECR registry using aws-actions/amazon-ecr-login
4. Build, tag, and push image -- Builds the Docker image from the repository root, tags it with $ECR_REGISTRY/$ECR_REPOSITORY:$GITHUB_SHA, and pushes it to ECR
5. Download task definition -- Fetches the current task definition JSON using aws ecs describe-task-definition
6. Fill in new image ID -- Renders the new image reference into the task definition using aws-actions/amazon-ecs-render-task-definition@v1
7. Deploy ECS task definition -- Deploys the updated task definition to the ECS service and waits for service stability using aws-actions/amazon-ecs-deploy-task-definition@v1

Usage Examples

# .github/workflows/deploy_to_ecs.yml
name: Deploy to Amazon ECS

on:
  push:
    branches:
      - master

env:
  AWS_REGION: us-east-1
  ECR_REPOSITORY: mage-ai-repo
  ECS_SERVICE: mage-service
  ECS_CLUSTER: mage-cluster
  ECS_TASK_DEFINITION: mage-task-def
  CONTAINER_NAME: mage-ai-container

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Checkout
        uses: actions/checkout@v5
      # ... remaining steps as in template

Related Pages

Implements Principle

• Principle:Mage_ai_Mage_ai_Source_Connector_Scaffolding

Requires Environment

• Environment:Mage_ai_Mage_ai_Python_3_9_Runtime