{"id":18258898,"url":"https://github.com/pottava/ecs-task-runner","last_synced_at":"2025-08-06T15:26:36.174Z","repository":{"id":39641025,"uuid":"144557478","full_name":"pottava/ecs-task-runner","owner":"pottava","description":"A synchronous task runner for AWS Fargate on Amazon ECS","archived":false,"fork":false,"pushed_at":"2024-11-10T11:20:14.000Z","size":139,"stargazers_count":17,"open_issues_count":1,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-04T19:32:57.736Z","etag":null,"topics":["cicd","docker","ecs","fargate","synchronous","task-runner"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pottava.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-13T09:25:24.000Z","updated_at":"2024-11-10T11:06:44.000Z","dependencies_parsed_at":"2024-06-19T01:51:12.255Z","dependency_job_id":"8241d461-3abc-45be-ac91-bd1cc84716eb","html_url":"https://github.com/pottava/ecs-task-runner","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/pottava/ecs-task-runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pottava%2Fecs-task-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pottava%2Fecs-task-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pottava%2Fecs-task-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pottava%2Fecs-task-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pottava","download_url":"https://codeload.github.com/pottava/ecs-task-runner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pottava%2Fecs-task-runner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269103233,"owners_count":24360314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-06T02:00:09.910Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cicd","docker","ecs","fargate","synchronous","task-runner"],"created_at":"2024-11-05T10:35:20.453Z","updated_at":"2025-08-06T15:26:36.112Z","avatar_url":"https://github.com/pottava.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A synchronous task runner for AWS Fargate on Amazon ECS\n\n[![CircleCI](https://circleci.com/gh/pottava/ecs-task-runner.svg?style=svg)](https://circleci.com/gh/pottava/ecs-task-runner)\n\n[![pottava/ecs-task-runner](http://dockeri.co/image/pottava/ecs-task-runner)](https://hub.docker.com/r/pottava/ecs-task-runner/)\n\nSupported tags and respective `Dockerfile` links:  \n・latest ([versions/3.0/Dockerfile](https://github.com/pottava/ecs-task-runner/blob/master/versions/3.0/Dockerfile))  \n・3.0 ([versions/3.0/Dockerfile](https://github.com/pottava/ecs-task-runner/blob/master/versions/3.0/Dockerfile))  \n・2.3 ([versions/2.3/Dockerfile](https://github.com/pottava/ecs-task-runner/blob/master/versions/2.3/Dockerfile))  \n・1 ([versions/1.2/Dockerfile](https://github.com/pottava/ecs-task-runner/blob/master/versions/1.2/Dockerfile))  \n\n## Description\n\nThis is a synchronous task runner for AWS Fargate. It runs a docker container on Fargate and waits for its done. Then it returns its standard output logs from CloudWatch Logs. All resources we need are created temporarily and remove them after the task finished.\n\n## Installation\n\ncurl (macOS):\n\n```sh\n$ curl -Lo ecs-task-runner https://github.com/pottava/ecs-task-runner/releases/download/3.0/ecs-task-runner_darwin_amd64 \\\n    \u0026\u0026 chmod +x ecs-task-runner\n```\n\ncurl (Linux):\n\n```sh\n$ curl -Lo ecs-task-runner https://github.com/pottava/ecs-task-runner/releases/download/3.0/ecs-task-runner_linux_amd64 \\\n    \u0026\u0026 chmod +x ecs-task-runner\n```\n\ngo:\n\n```console\ngo get github.com/pottava/ecs-task-runner/...\n```\n\ndocker:\n\n```console\ndocker pull pottava/ecs-task-runner\n```\n\n## Parameters\n\nCommon parameters:\n\nEnvironment Variables     | Argument        | Description                     | Required | Default\n------------------------- | --------------- | ------------------------------- | -------- | ---------\nAWS_ACCESS_KEY_ID         | access-key, a   | AWS `access key` for API access |          |\nAWS_SECRET_ACCESS_KEY     | secret-key, s   | AWS `secret key` for API access |          |\nAWS_DEFAULT_REGION        | region, r       | AWS `region` for API access     |          | us-east-1\nAWS_PROFILE               | profile         | AWS `profile` for API access    |          | default\nAWS_ASSUME_ROLE           | assume-role     | IAM Role ARN to be assumed      |          |\nAWS_MFA_SERIAL_NUMBER     | mfa-serial-num  | A serial number of MFA device   |          |\nAWS_MFA_TOKEN             | mfa-token       | A token for MFA                 |          |\nECS_CLUSTER               | cluster, c      | Amazon ECS cluster name         |          |\nEXEC_ROLE_NAME            | exec-role-name  | Name of an execution role       |          | ecs-task-runner\nTASK_TIMEOUT              | timeout, t      | Timeout minutes for the task    |          | 30\nEXTENDED_OUTPUT           | extended-output | True: meta data also returns    |          | false\n\nfor the `run` command:\n\nEnvironment Variables     | Argument        | Description                     | Required | Default\n------------------------- | --------------- | ------------------------------- | -------- | ---------\nDOCKER_IMAGE              |                 | Docker image to be run on ECS   | *        |\nFARGATE_SPOT              | spot            | True: fargate spot will be used |          | false\nFORCE_ECR                 | force-ecr, f    | True: you can use shortened name |         | false\nENTRYPOINT                | entrypoint      | Override `ENTRYPOINT` of the image |       |\nCOMMAND                   | command         | Override `CMD` of the image     |          |\nPORT                      | port, p         | Publish ports                   |          |\nENVIRONMENT               | environment, e  | Add `ENV` to the container      |          |\nUSER                      | docker-user     | The user inside the container   |          |\nLABEL                     | label, l        | Add `LABEL` to the container    |          |\nSUBNETS                   | subnets         | Fargate's Subnets               |          |\nSECURITY_GROUPS           | security-groups | Fargate's SecurityGroups        |          |\nTASKDEF_FAMILY            | taskdef-family  | ECS Task Definition family name |          | ecs-task-runner\nTASK_ROLE                 | task-role-arn   | ARN of an IAM Role for the task |          |\nCPU                       | cpu             | Requested vCPU to run Fargate   |          | 256\nMEMORY                    | memory          | Requested memory to run Fargate |          | 512\nNUMBER                    | number, n       | Number of tasks                 |          | 1\nPRIVATE_REGISTRY_USER     | user            | PrivateRegistry Username        |          |\nPRIVATE_REGISTRY_PASSWORD | password        | PrivateRegistry Password        |          |\nKMS_CUSTOMKEY_ID          | kms-key-id      | KMS custom key ID for SecretsManager |     |\nASSIGN_PUBLIC_IP          | assign-pub-ip   | True: Assigns public IP         |          | true\nREADONLY_ROOOTFS          | readonly-rootfs | Make the root file system read-only |      | false\nASYNC                     | async           | True: Does not wait for the job done |     | false\n\nfor the `stop` command:\n\nEnvironment Variables     | Argument        | Description                     | Required | Default\n------------------------- | --------------- | ------------------------------- | -------- | ---------\nREQUEST_ID                |                 | Resources ID to be stopped      | *        |\nTASK_ARN                  | task-arn        | Task ARNs to be stopped         |          |\n\n## Samples\n\n```console\n$ export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\n$ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\n$ ecs-task-runner run alpine --entrypoint env\n{\n  \"container-1\": [\n    \"2018-09-23T11:42:01+09:00: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\",\n    \"2018-09-23T11:42:01+09:00: HOSTNAME=ip-172-31-40-206.us-east-1.compute.internal\",\n    \"2018-09-23T11:42:01+09:00: AWS_DEFAULT_REGION=ap-northeast-1\",\n    \"2018-09-23T11:42:01+09:00: AWS_REGION=ap-northeast-1\",\n    \"2018-09-23T11:42:01+09:00: HOME=/root\"\n  ]\n}\n```\n\nUsing an assume role with MFA token\n\n```console\n$ unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY\n$\n$ export AWS_PROFILE=project-alpha-dev\n$ export AWS_ASSUME_ROLE=arn:aws:iam::123456789012:role/rolename\n$ export AWS_MFA_SERIAL_NUMBER=arn:aws:iam::123456789012:mfa/mfaname\n$ export AWS_MFA_TOKEN=123456\n$\n$ ecs-task-runner run alpine --entrypoint env\n{\n  \"container-1\": [\n    \"2018-09-23T11:42:01+09:00: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\",\n    \"2018-09-23T11:42:01+09:00: HOSTNAME=ip-172-31-40-206.us-east-1.compute.internal\",\n    \"2018-09-23T11:42:01+09:00: AWS_DEFAULT_REGION=ap-northeast-1\",\n    \"2018-09-23T11:42:01+09:00: AWS_REGION=ap-northeast-1\",\n    \"2018-09-23T11:42:01+09:00: HOME=/root\"\n  ]\n}\n$ echo $?\n0\n```\n\nThis app will return with an exit code of the containers:\n\n```console\n$ ecs-task-runner run alpine --entrypoint sh,-c --command \"exit 255\"\n{\n  \"container-1\": []\n}\n$ echo $?\n255\n```\n\nRun a container asynchronously with `--async` flag:\n\n```console\n$ ecs-task-runner run nginx --async -p 80 --security-groups sg-public-80-abcdefg\n{\n  \"RequestID\": \"ecs-task-runner-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n  \"Tasks\": [\n    {\n      \"PublicIP\": \"xx.xxx.xxx.xx\",\n      \"TaskARN\": \"arn:aws:ecs:us-east-1:xxxxxxxxxxxx:task/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\n    }\n  ]\n}\n```\n\nTo stop the asynchronous tasks:\n\n```console\n$ ecs-task-runner stop ecs-task-runner-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n{\n  \"container-1\": [\n    \"2018-09-23T22:34:37+09:00: zzz.zz.z.zzz - - [23/Sep/2018:13:34:37 +0000] \\\"GET / HTTP/1.1\\\" 200 612 \\\"-\\\" \\\"Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/52.0 Safari/537.36\\\" \\\"-\\\"\"\n  ]\n}\n```\n\n## Usage\n\nWith arguments:\n\n```console\necs-task-runner -a AKIAIOSFODNN7EXAMPLE -s wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY run sample/image\n```\n\nWith environment variables:\n\n```console\nexport AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\nexport AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\necs-task-runner run sample/image\n```\n\nWith ECR shortened image name:\n\n```console\nexport AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\nexport AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\necs-task-runner run --force-ecr my-ecr/image\n```\n\nWith a private registory:\n\n```console\nexport AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\nexport AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\nexport PRIVATE_REGISTRY_USER=user\nexport PRIVATE_REGISTRY_PASSWORD=password\necs-task-runner run sample/secret\n```\n\nWith the docker container:\n\n```console\nexport AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\nexport AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\ndocker run --rm -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY pottava/ecs-task-runner sample/image\n```\n\n## Troubleshooting\n\nIf the command returns non-zero exit code, you can try `--extended-output` to analyze the cause of failure.\n\n```console\nexport AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\nexport AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\necs-task-runner run sample/image --extended-output\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpottava%2Fecs-task-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpottava%2Fecs-task-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpottava%2Fecs-task-runner/lists"}