Release Commands & One-off Tasks

The release: command

A release: command runs once per deployment on the new task definition, before services receive traffic. A non-zero exit stops the deployment and leaves services on their previous revisions.

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"]

Use --skip-release to skip the command once or --release-timeout to override its timeout. The release runs inside the deploy lock, so its timeout must be shorter than --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 with the selected service's task definition, IAM role, security group, and environment. Use it for one-off work that does not require an existing healthy container. keel exec, by contrast, attaches to a running container.

-i attaches a terminal for a console or REPL. It requires /bin/sh in the image plus the AWS CLI and Session Manager plugin on your PATH. Keel stops the task 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. Keel speaks the SSM session protocol itself, so it needs neither the AWS CLI nor session-manager-plugin; --legacy-session uses those external tools as an escape hatch.

When audit.exec.require_reason is enabled, pass --reason. In the dashboard the exec shell opens in a pane instead of replacing the interface; ctrl+c is sent to the shell and ctrl+] exits the pane.