aws-actions/amazon-ecs-deploy-task-definition

Official actionCategory: Cloud Auth & DeployLatest v2View on GitHub

What it does

aws-actions/amazon-ecs-deploy-task-definition registers your task definition file as a new revision and deploys it to an ECS service. Without a service it only registers the revision.

It supports rolling deployments, CodeDeploy blue/green (via an AppSpec file), and running stand-alone tasks with run-task.

Usage

workflow (.yml)

permissions:
  id-token: write
  contents: read
steps:
  - uses: actions/checkout@v4
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789012:role/github-actions
      aws-region: us-east-1
  - uses: aws-actions/amazon-ecs-deploy-task-definition@v2
    with:
      task-definition: task-definition.json
      service: my-service
      cluster: my-cluster
      wait-for-service-stability: true

Inputs

Input	Description	Default	Required
`task-definition`	The path to the ECS task definition file to register.	-	Yes
`service`	The name of the ECS service to deploy to. If omitted, only registers the task definition.	-	No
`cluster`	The name of the ECS service's cluster. Defaults to the 'default' cluster.	-	No
`wait-for-service-stability`	Whether to wait for the ECS service to reach stable state after deploying. Defaults to not waiting.	-	No
`wait-for-minutes`	How long to wait for service stability, in minutes (default 30, max 6 hours).	-	No
`force-new-deployment`	Whether to force a new deployment of the service. Defaults to not forcing.	-	No
`run-task`	Whether to run a stand-alone task in the cluster (runs before any service update).	-	No

Outputs

Output	Description
`task-definition-arn`	The ARN of the registered ECS task definition.
`codedeploy-deployment-id`	The CodeDeploy deployment ID, when the service uses the CODE_DEPLOY controller.
`run-task-arn`	ARN(s) of tasks started by run-task, as a JSON array.

Notes

Run aws-actions/configure-aws-credentials first; this action uses the ambient AWS credentials.

Enable wait-for-service-stability so the job fails when the new tasks never become healthy, instead of reporting green on a broken rollout.

Common errors

is not authorized to perform: iam:PassRole means the CI role cannot pass the task execution/task role referenced in the task definition. Add an iam:PassRole grant for those role ARNs.
ServiceNotFoundException means the service/cluster pair is wrong, remember cluster defaults to the default cluster if unset.
A timeout while waiting for stability usually means new tasks are failing health checks or cannot pull the image; check the service events in ECS.

Security and pinning

Authenticate with OIDC role assumption via configure-aws-credentials rather than static keys, and scope the role to ecs:RegisterTaskDefinition, ecs:UpdateService, ecs:DescribeServices, and the specific iam:PassRole targets.

Alternatives and related

aws-actions/configure-aws-credentialsAuthenticate to AWS in a workflow, ideally by assuming a role with OIDC (no stored keys). aws-actions/amazon-ecr-loginLog in to Amazon ECR so a workflow can pull and push container images.

Frequently asked questions

How do I deploy a new image tag without editing JSON by hand?

Pair it with aws-actions/amazon-ecs-render-task-definition, which rewrites the image field of your task definition file, then pass the rendered file as task-definition.