Deployments

keel deploy builds and ships your application. By default it uses the CodeBuild pipeline; pass --local to build with Docker on your machine instead. A DynamoDB-backed lock prevents two people from deploying the same app+environment at once, and every deploy is recorded in a history log.

# Deploy all services via CodeBuild
keel deploy

# Deploy a single service and stream progress
keel deploy web --watch

# Build locally instead of using CodeBuild
keel deploy web --local

# Override a stale deploy lock
keel deploy --force --lock-timeout 30

# Review recent deployments
keel history
keel history --limit 50

The deploy pipeline

keel deploy runs in phases, so a failed migration never reaches production:

build  →  register a revision per service  →  run release once  →  promote each

1. Preflight — git checks run before anything builds. The deploy is pinned to exactly one commit, and Keel verifies that commit is reachable by CodeBuild (see below).
2. Build — one build per commit. Services that share a Dockerfile share a single CodeBuild project: the image is built once and tagged for each service, so a web task and a worker task can never end up on different builds of the same commit. A service that declares its own dockerfile gets its own build.
3. Register — a new task definition revision per service, pointing at the new image.
4. Release — the release: command runs once, on the new revision, before any service takes traffic. A non-zero exit fails the deploy and leaves every service on its previous revision.
5. Promote — each service is updated to the new revision.

Where the build gets your code

CodeBuild clones the commit you are deploying, so that commit has to be on a remote it can reach. keel deploy checks this before it builds anything, and what it does about a missing commit depends on who owns the repository.

source: github

pipeline.repo names your repository. Keel never pushes to it: that is where your team collaborates, with review, protected branches, and CI, and pushing on your behalf would route around all of it. A commit that is not on the remote stops the deploy with the git push to run.

A private repository needs a CodeConnections connection so CodeBuild can clone it. Create one per GitHub organization:

keel auth connect github my-org

The connection is created PENDING; finishing it means authorizing the AWS Connector GitHub App against the organization in the AWS console, which has no API. The command prints the URL and waits.

One connection covers an organization, not a repository or an app. The ARN is stored at /keel/connections/github/<org> in SSM, so every app deploying from that organization finds it with no further configuration. Set pipeline.connection_arn to override it for one app. keel deploy checks the connection is authorized before building — a connection reverts to PENDING if the app is uninstalled or access revoked, and that would otherwise surface as a clone failure minutes into a build.

source: codecommit with repo set

You are bringing an existing CodeCommit repository. Keel treats it exactly like GitHub: it clones from it and never pushes to it or manages it.

source: codecommit with repo unset

Keel creates the repository (<app>-<env>), and it is a build input rather than somewhere anyone works. Your team keeps using whatever they already use; keel up adds a git remote named keel, and keel deploy offers to push the commit there before building, signed with the credentials you already hold:

$ keel deploy
Deploying acme-api/production
  commit  abc1234  fix session timeout
  branch  main
  remote  keel (git-codecommit.us-east-1.amazonaws.com/v1/repos/acme-api-production)

  ! commit abc1234 is not on "keel", so CodeBuild cannot clone it
    Push abc1234 to the acme-api-production source repository and continue? [Y/n]

Use --no-push to turn the offer off, and --yes to accept it unattended.

Rolling back

keel rollback points a service back at the task-definition revision it ran before. Nothing is rebuilt — the revision already exists and its image is already in ECR — so it completes in seconds:

keel rollback              # every service, to its previous revision
keel rollback web --to 41  # one service, to a specific revision

WARNING

The release command is not re-run: rolling the code back does not roll a migration back.

Reconciling interrupted deploys

If a deploy is interrupted (network drop, ctrl-C, machine sleep), its record can be left in a non-terminal state. keel deploy reconcile inspects real AWS state and lets you resume, mark, or skip each stale record:

keel deploy reconcile