Repository files navigation

Runs an Amazon ECS task on ECS cluster.

Table of Contents

• Amazon ECS "Run Task" Action for GitHub Actions
• Usage
  • Task definition file
  • Task definition container image values
• Credentials and Region
• Permissions
• Troubleshooting
• License Summary

    -name:Run Task on Amazon ECSuses:smitp/amazon-ecs-run-task@v1with:task-definition:task-definition.jsoncluster:my-clustercount:1started-by:github-actions-${{ github.actor }}wait-for-finish:true

Seeaction.yml for the full documentation for this action's inputs and outputs.

It is highly recommended to treat the task definition "as code" by checking it into your git repository as a JSON file. Changes to any task definition attributes like container images, environment variables, CPU, and memory can be deployed with this GitHub action by editing your task definition file and pushing a new git commit.

An existing task definition can be downloaded to a JSON file with the following command. Account IDs can be removed from the file by removing thetaskDefinitionArn attribute, and updating theexecutionRoleArn andtaskRoleArn attribute values to contain role names instead of role ARNs.

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

Alternatively, you can start a new task definition file from scratch with the following command. In the generated file, fill in your attribute values and remove any attributes not needed for your application.

aws ecs register-task-definition \   --generate-cli-skeleton> task-definition.json

If you do not wish to store your task definition as a file in your git repository, your GitHub Actions workflow can download the existing task definition.

    -name:Download task definitionrun:|        aws ecs describe-task-definition --task-definition my-task-definition-family --query taskDefinition > task-definition.json

It is highly recommended that each time your GitHub Actions workflow runs and builds a new container image for deployment, a new container image ID is generated. For example, use the commit ID as the new image's tag, instead of updating the 'latest' tag with the new image. Using a unique container image ID for each deployment allows rolling back to a previous container image.

The task definition file can be updated prior to deployment with the new container image ID usingtheaws-actions/amazon-ecs-render-task-definition action. The following example builds a new container image tagged with the commit ID, inserts the new image ID as the image for themy-container container in the task definition file, and then deploys the rendered task definition file to ECS:

    -name:Configure AWS credentialsuses:aws-actions/configure-aws-credentials@v1with:aws-access-key-id:${{ secrets.AWS_ACCESS_KEY_ID }}aws-secret-access-key:${{ secrets.AWS_SECRET_ACCESS_KEY }}aws-region:us-east-2    -name:Login to Amazon ECRid:login-ecruses:aws-actions/amazon-ecr-login@v1    -name:Build, tag, and push image to Amazon ECRid:build-imageenv:ECR_REGISTRY:${{ steps.login-ecr.outputs.registry }}ECR_REPOSITORY:my-ecr-repoIMAGE_TAG:${{ github.sha }}run:|        docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .        docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG        echo "::set-output name=image::$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG"    -name:Fill in the new image ID in the Amazon ECS task definitionid:task-defuses:aws-actions/amazon-ecs-render-task-definition@v1with:task-definition:task-definition.jsoncontainer-name:my-containerimage:${{ steps.build-image.outputs.image }}    -name:Run Task on Amazon ECSuses:smitp/amazon-ecs-run-task@v1with:task-definition:task-definition.jsoncluster:my-clustercount:1started-by:github-actions-${{ github.actor }}wait-for-finish:true

This action relies on thedefault behavior of the AWS SDK for Javascript to determine AWS credentials and region.Usetheaws-actions/configure-aws-credentials action to configure the GitHub Actions environment with environment variables containing AWS credentials and your desired region.

We recommend followingAmazon IAM best practices for the AWS credentials used in GitHub Actions workflows, including:

• Do not store credentials in your repository's code. You may useGitHub Actions secrets to store credentials and redact credentials from GitHub Actions workflow logs.
• Create an individual IAM user with an access key for use in GitHub Actions workflows, preferably one per repository. Do not use the AWS account root user access key.
• Grant least privilege to the credentials used in GitHub Actions workflows. Grant only the permissions required to perform the actions in your GitHub Actions workflows. See the Permissions section below for the permissions required by this action.
• Rotate the credentials used in GitHub Actions workflows regularly.
• Monitor the activity of the credentials used in GitHub Actions workflows.

This action requires the following minimum set of permissions:

{"Version":"2012-10-17","Statement":[      {"Sid":"RegisterTaskDefinition","Effect":"Allow","Action":["ecs:RegisterTaskDefinition"         ],"Resource":"*"      },      {"Sid":"PassRolesInTaskDefinition","Effect":"Allow","Action":["iam:PassRole"         ],"Resource":["arn:aws:iam::<aws_account_id>:role/<task_definition_task_role_name>","arn:aws:iam::<aws_account_id>:role/<task_definition_task_execution_role_name>"         ]      },      {"Sid":"RunTask","Effect":"Allow","Action":"ecs:RunTask","Resource":"arn:aws:ecs:<region>:<aws_account_id>:task-definition/*:*"      },      {"Sid":"DescribeTasks","Effect":"Allow","Action":"ecs:DescribeTasks","Resource":"arn:aws:ecs:<region>:<aws_account_id>:task/*"      }   ]}

Note: the policy above assumes the account has opted in to the ECS long ARN format.

This action emits debug logs to help troubleshoot deployment failures. To see the debug logs, create a secret namedACTIONS_STEP_DEBUG with valuetrue in your repository.

This code is made available under the MIT license.