Fargate Deployer

Deploy a container to AWS ECS Fargate from a single declarative manifest — a long-running service behind an Application Load Balancer, or a set of EventBridge-scheduled tasks.

- uses: futuremoney/fargate-deployer@v1
  with:
    manifest: deploy/production.yaml
    role-to-assume: arn:aws:iam::111122223333:role/github-actions-deploy

That one step builds your image, pushes it to ECR, deploys the stack, and waits until ECS reports the service healthy. Your repository needs a Dockerfile and a manifest — no CDK app, no Node.js toolchain, no CloudFormation templates, no aws ecs update-service scripting.

Contents

• Why this exists
• Quickstart
• What it creates, and what you bring
• Action inputs
• Action outputs
• Scheduled tasks
• Calling it as a reusable workflow
• Running it outside GitHub Actions
• Using it inside your own CDK app
• Documentation

Why this exists

Most teams running Fargate already own the expensive, long-lived pieces: a VPC, an ECS cluster, one or two load balancers, a wildcard certificate. What they deploy over and over is the cheap part — a task definition, a service, a target group, a listener rule.

Existing options make that repetitive part harder than it should be. Writing CDK or Terraform per service means every team maintains infrastructure code to express the same six resources. aws ecs update-service scripting handles a new image but not a new port, health check or environment variable. Full-blown platforms want to own your VPC.

This action takes the middle path: you own the shared infrastructure, it owns the per-service resources. You describe the service in about twenty lines of YAML, and it deploys the same way every time, in any account, for anybody.

It is a public, generalised version of an internal deployer that has shipped production services for a couple of years. Everything account-specific that used to be hardcoded is now a manifest field.

Quickstart

1. Bootstrap the account, once

The deployer runs on AWS CDK, which needs a one-time bootstrap per account and region:

npx cdk bootstrap aws://111122223333/us-east-1

2. Create a deploy role

Set up GitHub OIDC and a role your workflow can assume — no long-lived AWS keys in your repository. docs/aws-setup.md has the trust policy, the permissions policy, and a copy-pasteable CloudFormation template.

3. Write a manifest

deploy/production.yaml:

kind: Service
name: hello-api
account: "111122223333"
region: us-east-1

cluster:
  name: my-cluster

network:
  vpcId: vpc-0abc123def4567890
  subnets:
    - subnet-0abc123def4567890
    - subnet-0fed987cba6543210

task:
  cpu: 256
  memory: 512
  containerPort: 8080
  environment:
    NODE_ENV: production
  secrets:
    DATABASE_URL: "arn:aws:secretsmanager:us-east-1:111122223333:secret:prod/db-AbCdEf:url::"

loadBalancer:
  listenerArn: arn:aws:elasticloadbalancing:us-east-1:111122223333:listener/app/my-alb/1234567890abcdef/abcdef1234567890
  securityGroupId: sg-0abc123def4567890
  hostHeaders: hello.example.com
  healthCheck:
    path: /health

Check it before you push anything — this touches no AWS APIs:

npx fargate-deployer validate --manifest deploy/production.yaml

4. Add the workflow

.github/workflows/deploy.yml:

name: Deploy
on:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write # required for OIDC

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: futuremoney/fargate-deployer@v1
        with:
          manifest: deploy/production.yaml
          role-to-assume: arn:aws:iam::111122223333:role/github-actions-deploy

Push to main. More patterns — multiple environments, promoting an image from staging to production, pull-request diffs — are in examples/workflows/.

What it creates, and what you bring

The split is deliberate. Anything shared between services, expensive to replace, or dangerous to delete stays yours.

| You bring (referenced by ARN or ID) | It creates (owned by the stack) | | --- | --- | | VPC and subnets | ECS task definition | | ECS cluster | ECS service, or EventBridge rules | | Application Load Balancer and listener | ALB target group and listener rule | | ACM certificate | CloudWatch log group | | Secrets Manager secrets / SSM parameters | Task security group (if you don't supply one) | | IAM roles (optional) | Task and execution IAM roles (if you don't supply them) | | | Auto-scaling target and policies |

Everything in the right column is deleted cleanly when you delete the stack. Nothing in the left column is ever modified, with one deliberate exception: when you give loadBalancer.securityGroupId, an ingress rule is added so the load balancer can reach your tasks. Set manageSecurityGroupRules: false to manage that yourself.

Roles and security groups are the accessibility knob. Omit them and you get working defaults with the exact permissions the task needs — image pull, log writes, read access to precisely the secrets you listed, and ECS Exec. Supply them and the deployer treats them as immutable and touches nothing.

Action inputs

Only manifest is required.

What to deploy

| Input | Default | Description | | --- | --- | --- | | manifest | — | Required. Path to the manifest, e.g. deploy/production.yaml. | | image | build one | Deploy this exact image instead of building. Skips build and push entirely. | | command | deploy | deploy, diff, synth, validate or destroy. |

AWS authentication

| Input | Default | Description | | --- | --- | --- | | role-to-assume | — | IAM role ARN to assume via GitHub OIDC. Recommended. Needs permissions: id-token: write. | | role-session-name | fargate-deployer | Session name for the assumed role. | | role-external-id | — | External ID, if the role's trust policy requires one. | | role-duration-seconds | 3600 | Session lifetime. Raise it if a slow rollout can outlast an hour. | | aws-access-key-id | — | Static access key, when OIDC is not available. | | aws-secret-access-key | — | Secret key that goes with it. | | aws-session-token | — | Required when the key and secret are temporary STS credentials. | | aws-region | from manifest | Override the region. |

Credentials go in with:, not secrets: — an action has no secrets: block. The values are still masked in logs. If you would rather pass them as secrets:, call the reusable workflow instead. A worked example using access keys is in examples/workflows/iam-access-keys.yml.

Four combinations are supported, and one non-combination:

| What you set | What happens | | --- | --- | | role-to-assume | OIDC. No stored credentials. Recommended. | | aws-access-key-id + aws-secret-access-key | Static IAM user credentials. | | …plus aws-session-token | Temporary STS credentials. | | …plus role-to-assume | Assume that role from those keys — the usual pattern when a low-privilege CI user chains into a deploy role. | | Nothing | The credential step is skipped, and whatever the job already has is used — credentials set by an earlier step, or a self-hosted runner's instance profile. |

Image build

| Input | Default | Description | | --- | --- | --- | | ecr-repository | manifest name | ECR repository to push to. | | create-ecr-repository | true | Create the repository if it does not exist. | | image-tag | github.sha | Tag for the built image. | | push-latest | false | Also tag the image latest. | | dockerfile | Dockerfile | Path to the Dockerfile, relative to context. | | context | . | Docker build context. | | build-args | — | KEY=VALUE per line. Visible in image history — not for secrets. | | build-secrets | — | KEY=VALUE per line, read in the build via RUN --mount=type=secret,id=KEY. | | platforms | from manifest | Build platform. Follows task.runtimePlatform.cpuArchitecture. | | provenance | false | Attach SLSA provenance. Off because the resulting image index is not usable by ECS. |

Deployment behaviour

| Input | Default | Description | | --- | --- | --- | | bootstrap | false | Run cdk bootstrap first. Useful for a brand-new account; turn it off afterwards. | | wait-for-stability | true | Wait for ECS to report the service stable, and print recent service events on failure. | | cdk-args | — | Extra flags passed straight to the CDK CLI. | | working-directory | . | Directory that manifest and context are relative to. | | node-version | 20 | Node.js used to run the deployer itself, not your build. |

Action outputs

| Output | Description | | --- | --- | | image | Full image URI that was deployed | | image-digest | Digest of the pushed image | | stack-name | CloudFormation stack name | | service-name | ECS service name (Service manifests) | | cluster | ECS cluster deployed into | | region / account | Target region and account from the manifest | | kind | Service or ScheduledTasks | | log-group | CloudWatch log group the tasks write to | | alb-dns-name | Load balancer DNS name — the CNAME target for your DNS records | | alb-hosted-zone-id | Load balancer hosted zone ID, for a Route 53 alias record |

Pointing DNS at the service

After a deploy the job summary lists the record to create for each host header you routed:

DNS

Point each hostname at the load balancer:

| Record | Type | Value | |---|---|---| | hello.example.com | CNAME | my-alb-1234567890.us-east-1.elb.amazonaws.com |

An apex domain cannot hold a CNAME — use a Route 53 alias A record to hosted zone Z35SXDOTRQ7X7K instead.

The same values are available as outputs, so the records can be created by the workflow rather than by hand:

- id: deploy
  uses: futuremoney/fargate-deployer@v1
  with:
    manifest: deploy/production.yaml
    role-to-assume: arn:aws:iam::111122223333:role/github-actions-deploy

- name: Upsert the DNS record
  run: |
    aws route53 change-resource-record-sets \
      --hosted-zone-id "$MY_ZONE" \
      --change-batch '{
        "Changes": [{
          "Action": "UPSERT",
          "ResourceRecordSet": {
            "Name": "hello.example.com",
            "Type": "A",
            "AliasTarget": {
              "HostedZoneId": "${{ steps.deploy.outputs.alb-hosted-zone-id }}",
              "DNSName": "${{ steps.deploy.outputs.alb-dns-name }}",
              "EvaluateTargetHealth": true
            }
          }
        }]
      }'

Resolving the name costs one elasticloadbalancing:DescribeLoadBalancers call after the deploy. If the deploy role lacks that permission the step warns and the outputs are empty — the deploy itself still succeeds.

Scheduled tasks

Change kind and the same action deploys cron jobs instead — one EventBridge rule per entry, each starting a Fargate task:

kind: ScheduledTasks
name: data-sync
account: "111122223333"
region: us-east-1

cluster: { name: my-cluster }
network:
  vpcId: vpc-0abc123def4567890
  subnets: [subnet-0abc123def4567890]

task:
  cpu: 256
  memory: 512

tasks:
  - name: nightly-sync
    schedule: cron(0 6 * * ? *) # 06:00 UTC
    command: ["node", "dist/jobs/sync.js"]

  - name: hourly-prices
    schedule: rate(1 hour)
    command: ["node", "dist/jobs/prices.js"]

See docs/scheduled-tasks.md for schedule syntax, per-job overrides, and how to disable a job without deleting it.

Calling it as a reusable workflow

The action is the primary interface, but a workflow_call wrapper ships alongside it for callers who prefer that shape — most often because AWS credentials already arrive through a secrets: block, which an action cannot accept:

jobs:
  deploy:
    uses: futuremoney/fargate-deployer/.github/workflows/fargate-deploy.yml@v1
    with:
      manifest: deploy/development.yaml
    secrets:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID_DEVELOPMENT }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY_DEVELOPMENT }}

It brings its own job, so there is no runs-on, no steps, and no actions/checkout. Extra inputs it adds over the action: environment (to apply a GitHub environment's protection rules) and runner. Extra secrets: AWS_SESSION_TOKEN and BUILD_SECRETS.

Two things to know. Reusable workflows cannot be listed on the Marketplace — only actions can — so this is referenced by path rather than by name. And it adds a job boundary, so permissions and environment apply to the whole called workflow rather than to one step.

See examples/workflows/reusable-workflow-with-secrets.yml.

Running it outside GitHub Actions

The action is a thin wrapper around a CLI, so the exact command CI runs also runs on your laptop, in GitLab CI, or from a Makefile:

npx fargate-deployer validate --manifest deploy/production.yaml
npx fargate-deployer diff     --manifest deploy/production.yaml --image my-image:tag
npx fargate-deployer deploy   --manifest deploy/production.yaml --image my-image:tag
npx fargate-deployer destroy  --manifest deploy/production.yaml --image my-image:tag

It uses your ambient AWS credentials, the same as any other AWS CLI tool.

Running diff locally before pushing is the fastest way to see what a deploy would change — it is the same synthesis CI performs, so the output matches.

Using it inside your own CDK app

If your repository already owns CDK infrastructure, import the stack into the app you have rather than deploying a second one:

import * as cdk from 'aws-cdk-lib';
import { createStack, loadManifest } from 'fargate-deployer';

const app = new cdk.App();
const infra = new MyInfraStack(app, 'my-infra');

const config = loadManifest('deploy/production.yaml');
config.task.environment.QUEUE_URL = infra.queue.queueUrl; // a CDK token

createStack({ app, config, image: process.env.IMAGE! });

cdk deploy --all then covers both, and CDK turns that token into a real cross-stack reference.

This is not just a preference. The CLI synthesises its own single-stack app, so any other stacks in your repository are invisible to it — they do not deploy, and nothing warns you. If you own CDK already, this is the mode you want.

docs/construct-mode.md covers the whole of it.

Documentation

| | | | --- | --- | | Manifest reference | Every field, its default, and when to set it | | AWS setup | Bootstrap, OIDC, IAM policies, prerequisites | | Scheduled tasks | Cron jobs in depth | | Architecture | What is created, how it is named, why | | Construct mode | Using the stacks inside a CDK app you already have | | Troubleshooting | Common failures and what they mean | | Contributing | Development setup and release process | | Security policy | Reporting a vulnerability, and the action's trust boundaries | | Changelog | What changed in each release |

License

MIT