{"meta":{"title":"Deploying to Amazon Elastic Container Service","intro":"Learn how to deploy a project to Amazon Elastic Container Service (ECS) as part of a continuous deployment (CD) workflow.","product":"GitHub Actions","breadcrumbs":[{"href":"/en/actions","title":"GitHub Actions"},{"href":"/en/actions/how-tos","title":"How-tos"},{"href":"/en/actions/how-tos/deploy","title":"Deploy"},{"href":"/en/actions/how-tos/deploy/deploy-to-third-party-platforms","title":"Deploy to third-party platforms"},{"href":"/en/actions/how-tos/deploy/deploy-to-third-party-platforms/amazon-elastic-container-service","title":"Amazon Elastic Container Service"}],"documentType":"article"},"body":"# Deploying to Amazon Elastic Container Service\n\nLearn how to deploy a project to Amazon Elastic Container Service (ECS) as part of a continuous deployment (CD) workflow.\n\n## Prerequisites\n\nBefore creating your GitHub Actions workflow, you will first need to complete the following setup steps for Amazon ECR and ECS:\n\n1. Create an Amazon ECR repository to store your images.\n\n   For example, using [the AWS CLI](https://aws.amazon.com/cli/):\n\n   ```bash copy\n   aws ecr create-repository \\\n       --repository-name MY_ECR_REPOSITORY \\\n       --region MY_AWS_REGION\n\n   ```\n\n   Ensure that you use the same Amazon ECR repository name (represented here by `MY_ECR_REPOSITORY`) for the `ECR_REPOSITORY` variable in the workflow below.\n\n   Ensure that you use the same AWS region value for the `AWS_REGION` (represented here by `MY_AWS_REGION`) variable in the workflow below.\n\n2. Create an Amazon ECS task definition, cluster, and service.\n\n   For details, follow the [Getting started wizard on the Amazon ECS console](https://us-east-2.console.aws.amazon.com/ecs/home?region=us-east-2#/firstRun), or the [Getting started guide](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/getting-started-fargate.html) in the Amazon ECS documentation.\n\n   Ensure that you note the names you set for the Amazon ECS service and cluster, and use them for the `ECS_SERVICE` and `ECS_CLUSTER` variables in the workflow below.\n\n3. Store your Amazon ECS task definition as a JSON file in your GitHub repository.\n\n   The format of the file should be the same as the output generated by:\n\n   ```bash copy\n\n   aws ecs register-task-definition --generate-cli-skeleton\n\n   ```\n\n   Ensure that you set the `ECS_TASK_DEFINITION` variable in the workflow below as the path to the JSON file.\n\n   Ensure that you set the `CONTAINER_NAME` variable in the workflow below as the container name in the `containerDefinitions` section of the task definition.\n\n4. Create GitHub Actions secrets named `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to store the values for your Amazon IAM access key.\n\n   For more information on creating secrets for GitHub Actions, see [Using secrets in GitHub Actions](/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository).\n\n   See the documentation for each action used below for the recommended IAM policies for the IAM user, and methods for handling the access key credentials.\n\n5. Optionally, configure a deployment environment. Environments are used to describe a general deployment target like `production`, `staging`, or `development`. When a GitHub Actions workflow deploys to an environment, the environment is displayed on the main page of the repository. You can use environments to require approval for a job to proceed, restrict which branches can trigger a workflow, gate deployments with custom deployment protection rules, or limit access to secrets. For more information about creating environments, see [Managing environments for deployment](/en/actions/deployment/targeting-different-environments/managing-environments-for-deployment).\n\n## Creating the workflow\n\nOnce you've completed the prerequisites, you can proceed with creating the workflow.\n\nThe following example workflow demonstrates how to build a container image and push it to Amazon ECR. It then updates the task definition with the new image ID, and deploys the task definition to Amazon ECS.\n\nEnsure that you provide your own values for all the variables in the `env` key of the workflow.\n\nIf you configured a deployment environment, change the value of `environment` to be the name of your environment. If you did not configure an environment or if your workflow is in a private repository and you do not use GitHub Enterprise Cloud, delete the `environment` key.\n\n```yaml copy\n# This workflow uses actions that are not certified by GitHub.\n# They are provided by a third-party and are governed by\n# separate terms of service, privacy policy, and support\n# documentation.\n\n# GitHub recommends pinning actions to a commit SHA.\n# To get a newer version, you will need to update the SHA.\n# You can also reference a tag or branch, but the action may change without warning.\n\nname: Deploy to Amazon ECS\n\non:\n  push:\n    branches:\n      - main\n\nenv:\n  AWS_REGION: MY_AWS_REGION                   # set this to your preferred AWS region, e.g. us-west-1\n  ECR_REPOSITORY: MY_ECR_REPOSITORY           # set this to your Amazon ECR repository name\n  ECS_SERVICE: MY_ECS_SERVICE                 # set this to your Amazon ECS service name\n  ECS_CLUSTER: MY_ECS_CLUSTER                 # set this to your Amazon ECS cluster name\n  ECS_TASK_DEFINITION: MY_ECS_TASK_DEFINITION # set this to the path to your Amazon ECS task definition\n                                               # file, e.g. .aws/task-definition.json\n  CONTAINER_NAME: MY_CONTAINER_NAME           # set this to the name of the container in the\n                                               # containerDefinitions section of your task definition\n\njobs:\n  deploy:\n    name: Deploy\n    runs-on: ubuntu-latest\n    environment: production\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v6\n\n      - name: Configure AWS credentials\n        uses: aws-actions/configure-aws-credentials@0e613a0980cbf65ed5b322eb7a1e075d28913a83\n        with:\n          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}\n          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n          aws-region: ${{ env.AWS_REGION }}\n\n      - name: Login to Amazon ECR\n        id: login-ecr\n        uses: aws-actions/amazon-ecr-login@62f4f872db3836360b72999f4b87f1ff13310f3a\n\n      - name: Build, tag, and push image to Amazon ECR\n        id: build-image\n        env:\n          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}\n          IMAGE_TAG: ${{ github.sha }}\n        run: |\n          # Build a docker container and\n          # push it to ECR so that it can\n          # be deployed to ECS.\n          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .\n          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG\n          echo \"image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG\" >> $GITHUB_OUTPUT\n\n      - name: Fill in the new image ID in the Amazon ECS task definition\n        id: task-def\n        uses: aws-actions/amazon-ecs-render-task-definition@c804dfbdd57f713b6c079302a4c01db7017a36fc\n        with:\n          task-definition: ${{ env.ECS_TASK_DEFINITION }}\n          container-name: ${{ env.CONTAINER_NAME }}\n          image: ${{ steps.build-image.outputs.image }}\n\n      - name: Deploy Amazon ECS task definition\n        uses: aws-actions/amazon-ecs-deploy-task-definition@df9643053eda01f169e64a0e60233aacca83799a\n        with:\n          task-definition: ${{ steps.task-def.outputs.task-definition }}\n          service: ${{ env.ECS_SERVICE }}\n          cluster: ${{ env.ECS_CLUSTER }}\n          wait-for-service-stability: true\n```\n\n## Further reading\n\nFor the original workflow template, see [`aws.yml`](https://github.com/actions/starter-workflows/blob/main/deployments/aws.yml) in the GitHub Actions `starter-workflows` repository.\n\nFor more information on the services used in these examples, see the following documentation:\n\n* [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the Amazon AWS documentation.\n* Official AWS [Configure AWS Credentials](https://github.com/aws-actions/configure-aws-credentials) action.\n* Official AWS [Amazon ECR \"Login\"](https://github.com/aws-actions/amazon-ecr-login) action.\n* Official AWS [Amazon ECS \"Render Task Definition\"](https://github.com/aws-actions/amazon-ecs-render-task-definition) action.\n* Official AWS [Amazon ECS \"Deploy Task Definition\"](https://github.com/aws-actions/amazon-ecs-deploy-task-definition) action."}