Release Commands & One-off Tasks

The release: command

A release: command runs once per deploy, on the newly registered task definition, before any service takes traffic. A non-zero exit fails the deploy and leaves every service on its previous revision — a failed migration never reaches production.

services:
  web:
    type: web
    port: 3000
    health_check: /up
    command: bundle exec thrust ./bin/rails server
  sidekiq:
    type: worker
    command: ["bundle", "exec", "sidekiq"]

release:
  command: bundle exec rails db:migrate
  service: web          # whose task role, security group, and env to run with
  timeout: 20m          # default 15m

release: also accepts the shorthand forms:

release: bundle exec rails db:migrate
release: ["sh", "-c", "a && b"]

--skip-release skips the command for one deploy; --release-timeout overrides the configured timeout. The release runs inside the deploy lock, so two deploys can never run two migrations at once — which is why its timeout must fit inside --lock-timeout.

keel run — one-off tasks

keel run -- bundle exec rails db:migrate
keel run --service sidekiq -- rake reports:backfill
keel run -i -- bundle exec rails console

keel run starts a new ECS task using a service's task definition, IAM role, security group, and environment. Contrast with keel exec, which attaches to an already-running container — no help when nothing is healthy yet, often the case when a migration is the thing that would make it healthy.

-i attaches a terminal for a console or REPL. It requires /bin/sh in the image and the session-manager-plugin, same as keel exec. The task is always stopped when the session ends.

The command runs with the chosen service's role and security group. If only one of your services can reach the database, name it with --service or release.service.

keel exec — shell into a running task

keel exec web
keel exec web -c 'bin/rails runner "puts User.count"'

Requires /bin/sh in the image and the AWS session-manager-plugin installed locally.