ecs-deploy: A Shell-Based Blue-Green Deployment Workflow for Amazon ECS

ecs-deploy Targets Existing ECS Services and Task Definitions

ecs-deploy addresses deployments for workloads that already have an Amazon ECS task definition and, for service deployments, an existing ECS service. It is intended for engineers who update container images or task revisions through a command line rather than manually editing every deployment setting. The project presents the workflow as blue-green deployment, although its implementation is centered on ECS Task Definition and Service entities.

The tool can deploy either an ECS service or a standalone task definition. A service deployment needs a cluster, a service name, and an image. A task-definition update can start from an existing definition and apply a new image. For multi-container tasks, `--tag-only` can replace the tag on every image found in the task. This makes the script relevant to applications whose services include several containers, but the documentation does not describe infrastructure provisioning, container image builds, load testing, or application health endpoints.

The intended audience is therefore narrower than users of a complete deployment service. It fits a pipeline or operator workstation that already has AWS access, knows the ECS cluster and service names, and wants a repeatable command for registering a revised task definition and updating an existing service. Its interface is deliberately command oriented: required credentials, region or profile, cluster, service, and image settings are supplied as arguments or environment variables.

ecs-deploy Revises Task Definitions Through Image and Tag Changes

According to the README, `ecs-deploy` uses the relationship between an ECS Task Definition and Service. The task definition acts as the template for containers that make up the application. The script changes the selected image or image tag, creates or selects a deployment basis, and directs ECS to run the revised task definition through an existing service.

Several flags define what the revision changes. `-i | --image` accepts an image such as `repo/image:latest`. `-e | --tag-env-var` takes the tag from an environment variable and overrides a tag included in the image argument. `-to | --tag-only` applies one new tag to all images in a multi-container task. If neither a tag in the image nor a tag environment variable provides one, the documented fallback is `latest`. That default can be convenient, but it also means deployment automation should avoid relying on an implicit movable tag when reproducibility matters.

The script offers two ways to choose the base revision. `--use-latest-task-def` selects the most recently created task definition instead of the revision last used by the service. `--task-definition-file` accepts a file containing the task definition to deploy. For existing metadata, `--copy-task-definition-tags` copies tags from the existing definition to the new revision. These options distinguish between updating an already registered revision and supplying a definition file.

Deployment behavior can also be tuned through `-D | --desired-count`, `-m | --min`, and `-M | --max`. Their defaults for the healthy percentage and maximum percentage are documented as 100 and 200. `-t | --timeout` defaults to 90 seconds while the script monitors whether tasks from the new definition are running.

ecs-deploy Monitors ECS and Can Reverse an Unsuccessful Revision

Once an update is initiated, `ecs-deploy` monitors the ECS service until the new task definition has running tasks. This is service-state monitoring, not application-level validation. The documentation does not say that `ecs-deploy` sends requests to the deployed application, checks a business endpoint, or evaluates custom health criteria. A task can therefore be running according to ECS without that fact proving that the application is healthy.

The `--enable-rollback` option asks the script to restore the previous task definition if the new version is not running before `TIMEOUT`. Rollback is optional rather than unconditional, and it depends on the deployment failing to reach the script's running-task condition within the configured period. The documentation does not explain every failure path, including permissions errors, malformed task definitions, or an AWS CLI failure during rollback.

Revision cleanup is controlled by `--max-definitions`. The requested number must be at least 1, and it means the number of task definition revisions the script seeks to persist. The README warns that cleanup can deregister revisions that do not match the retention criteria even when they were created manually. Deregistration occurs only after a successful deployment. That makes the option more than ordinary history pruning, because an administrator could lose manually created but unwanted revisions from the retained set. Its exact selection behavior should be checked against the script version before enabling aggressive cleanup.

For services that cannot finish draining old tasks within the normal monitoring period, `--skip-deployments-check` exists. It relaxes a deployment check, but it can also allow execution to proceed when ECS still reports a deployment-related condition. This flag trades certainty for tolerance of slow task replacement and is better treated as an exception than a routine default.

Installing ecs-deploy Requires AWS CLI, jq, and Shell Execution

The documented host requirements are the AWS Command Line Interface, `jq`, and permission to install an executable script. Install and configure `aws-cli` first, then install `jq`. The project places the downloaded `ecs-deploy` file at `/usr/bin/ecs-deploy` and makes it executable.

The README's installation commands are:

curl https://raw.githubusercontent.com/sil-org/ecs-deploy/master/ecs-deploy | sudo tee /usr/bin/ecs-deploy
sudo chmod +x /usr/bin/ecs-deploy

The first command fetches the script from the repository's `master` branch and writes it to `/usr/bin/ecs-deploy`. The second makes that file executable. Because this installs content from a remote branch rather than a versioned release artifact, teams that require repeatable builds should account for that installation choice in their own asset process.

For a first service deployment, configure AWS credentials and the default region through the documented environment variables, or use another supported authentication method. Then replace the example cluster, service, and image values with the names from the existing ECS deployment:

ecs-deploy -c my-cluster-name -n my-service-name -i my.private.repo.com/frontend_container:latest

The README presents this as a simple service deployment using AWS environment variables. Before executing it, confirm that the named cluster and service already exist and that the IAM principal can perform the ECS operations needed to register task definitions and update the service.

AWS Credentials Can Come from Environment Variables, Profiles, or an Instance Role

`ecs-deploy` offers several credential paths. `AWS_ACCESS_KEY_ID` can hold the access key, `AWS_SECRET_ACCESS_KEY` can hold the secret key, and `AWS_DEFAULT_REGION` can supply the region. The corresponding `-k`, `-s`, and `-r` options allow those values to be passed directly.

AWS profiles are available through `-p | --profile`. When a profile is selected, the README says the access key, secret key, and region arguments are not required. That makes profile selection a cleaner fit for workstation automation and delegated credentials represented by STS.

An EC2 instance role is another documented path. `--aws-instance-profile` asks the script to use the IAM role associated with the current AWS instance and can only be used from a running AWS instance. When it is selected, access key and secret key arguments are not required.

There is also `-a | --aws-assume-role`, which takes an ARN for a role to assume during operations. The README names the option but does not describe its session duration or the exact permission model. The project also exposes `-v | --verbose` for more detailed output. During adoption, the first access mode to verify is the intended IAM role or profile because a syntactically valid deployment command can still fail when its ECS permissions do not match the cluster and service being changed.

ecs-deploy Is Feature Complete and Its Shell Design Limits Extensibility

The README explicitly places `ecs-deploy` in maintenance mode. It describes the project as feature complete and says pull requests are generally considered only for bug fixes or support for new AWS CLI features. The repository is not archived, and the last push was on 2026-07-01. That maintenance declaration is more important than the recency of the push: new deployment features should not be expected as a normal part of the project's direction.

Release 3.10.27, dated 2026-07-01, is described as fixing task definition max definitions handling. Releases 3.10.26 and 3.10.25 are listed as bug fixes on 2026-06-15 and 2026-06-13. This pattern is consistent with maintenance-mode changes, although release descriptions alone do not establish compatibility with every future AWS API change.

The implementation is a Shell script that depends on `aws` and `jq`. That keeps installation small and makes the command readable, but it also means behavior is tied to those command-line interfaces. The repository includes `test.bats`, `run-tests.sh`, and a Compose-based test environment, yet the README does not document a public plugin system, structured deployment policy file, or alternate deployment engine.

A real alternative is to operate ECS directly through the AWS CLI. The AWS CLI is already required by `ecs-deploy`, while ECS already provides service update and task-definition revision mechanisms. The difference is that direct use requires the deployment process to handle command construction and monitoring itself. `ecs-deploy` supplies a ready-made interface around that ECS model, including image tag handling, deployment settings, timeout monitoring, revision retention, and optional rollback. It is appropriate when those conventions are useful, but direct AWS CLI orchestration offers more control for pipelines with custom health gates or deployment logic.

Standalone ECS Tasks Have Separate Network and Result Options

The `--run-task` option runs the created task immediately without a service name. That mode is useful when the task is a one-off ECS job rather than a continuously managed service. The documentation also provides `--wait-for-success`, which waits for task completion and an `exitCode` of 0.

A standalone run requires attention to ECS task execution details. `--launch-type` selects the ECS launch type. `--platform-version` selects the Fargate platform version. `--network-configuration` supplies network configuration and is required for task definitions using the `awsvpc` network mode. The README states that this option is not supported for other network modes.

These parameters expose a limitation of the Shell interface: the deployment workflow does not remove the need to understand ECS constraints. A task definition that uses `awsvpc` cannot be treated the same as one using a different network mode. Similarly, `--wait-for-success` checks task completion according to the documented exit code, but the README does not describe custom success criteria beyond that value.

Licensing is MIT, so the repository identifies a permissive open-source license. The project documentation does not provide additional warranty, liability, or compliance terms, and this review does not interpret those legal effects. The practical licensing point is limited to confirming that the MIT file matches the organization's policy for redistribution and internal modification.

Editorial conclusion

Adopt ecs-deploy when an ECS team values a small Shell interface for task-definition revisions, deployment monitoring, and rollback without maintaining a deployment application. Do not adopt it as a general continuous-delivery platform or for ECS resource creation outside its documented scope. Before installation, verify that your IAM permissions, ECS network settings, task definition format, and desired cleanup policy match the flags and defaults documented by the project.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sil-org/ecs-deploy on GitHub