Amazon ECS Deploy Task Definition

You can use this action to trigger an ad-hoc ECS task run, which is useful for initialization tasks like database migrations. When run-task: true is used, the service update will not proceed until the ad-hoc task exits successfully if wait-for-task-stopped: true is also set.

Note: For FARGATE launch types, your task definition must use the awsvpc network mode and you must specify a network configuration (refer to action.yml for details).

    - name: Deploy to Amazon ECS
      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
        run-task: true
        wait-for-task-stopped: true

Use the aws-actions/amazon-ecs-deploy-task-definition action to register an Amazon ECS task definition and deploy it to an ECS service.

When running a one-off task (instead of a service), you will typically need to provide subnet IDs, subnet groups, and an assign-public-ip value. Note that assign-public-ip is only applied if a subnet or security group is defined.

- name: Deploy to Amazon ECS
  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

It is recommended to treat your task definition as code by checking a JSON file into your git repository. You can manage these files in three ways:

1. Download an existing definition: Use the AWS CLI to pull the current configuration into a file.
2. Generate a new skeleton: Use the AWS CLI to create a template file to fill in manually.
3. Download during workflow: If you don't want to store the file in git, use the AWS CLI within your GitHub Actions workflow to download it on the fly.

# Download existing task definition
aws ecs describe-task-definition \
   --task-definition my-task-definition-family \
   --query taskDefinition > task-definition.json

# Generate a new skeleton
aws ecs register-task-definition \
   --generate-cli-skeleton > task-definition.json

By default, the action removes empty strings, arrays, and objects from the task definition to align with ECS defaults. If you need to explicitly override a non-null default value with an empty or null value, use keep-null-value-keys.

Provide a comma-separated list of key names to ensure their empty values are retained during registration.

- name: Deploy to Amazon ECS
  uses: aws-actions/amazon-ecs-deploy-task-definition@v2
  with:
    task-definition: task-definition.json
    service: my-service
    cluster: my-cluster
    keep-null-value-keys: tag,command,placementConstraints
    wait-for-service-stability: true

To handle transient failures (like eventual consistency or temporary AWS API errors) during task definition registration or service updates, use the max-retries input.

• Default: 3
• Minimum: 0 (no retries)

- name: Deploy to Amazon ECS
  uses: aws-actions/amazon-ecs-deploy-task-definition@v2
  with:
    task-definition: task-definition.json
    service: my-service
    cluster: my-cluster
    max-retries: 5
    wait-for-service-stability: true

The AWS SDK uses exponential backoff by default, which can cause delays of up to 120 seconds between polls. To use a consistent polling interval and detect service stability faster, set wait-max-delay-seconds to your desired interval in seconds.

    - name: Deploy to Amazon ECS
      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
        wait-max-delay-seconds: 15

The action starts by reading a task definition file (YAML or JSON) from your repository. It automatically cleans the input by:

1. Removing attributes returned by the ECS API that are invalid for registration (e.g., taskDefinitionArn, revision, status).
2. Cleaning null or empty values, unless they are explicitly preserved via the keep-null-value-keys input.
3. Ensuring valid object structures for proxyConfiguration and container environment variables.

If registration fails, the action will log the exact task definition contents to the debug logs to help troubleshoot schema errors.

You can control how tags are applied to your tasks:

• enable-ecs-managed-tags: Set to true to enable Amazon ECS-managed tags (aws:ecs:serviceName and aws:ecs:clusterName).
• propagate-tags: Set to SERVICE to propagate custom tags from your existing service to the tasks.

- name: Deploy Amazon ECS task definition
  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
    enable-ecs-managed-tags: true
    propagate-tags: SERVICE

You can apply tags to your tasks using the following inputs:

• enable-ecs-managed-tags: Set to true to enable Amazon ECS-managed tags (e.g., aws:ecs:clusterName).
• run-task-tags: A JSON array of custom tags to apply.

    - name: Deploy to Amazon ECS
      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
        run-task: true
        enable-ecs-managed-tags: true
        run-task-tags: '[{"key": "project", "value": "myproject"}]'
        wait-for-task-stopped: true