Deployments

keel deploy builds and releases your application. It uses CodeBuild by default; pass --local to build with Docker on your machine. A DynamoDB lock serializes deployments to each app and environment, and Keel records every deployment in its history.

# 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 first deploy

keel up creates new services at zero tasks because their image tags do not exist until the first build. It then offers to run the initial deployment. Use keel up --deploy -y to do both without prompts. After the first deployment, keel scale and autoscaling control task counts; later infrastructure updates do not reset them to the value in the config.

Docker or buildpacks

pipeline.build selects auto (the default), docker, or buildpack. In auto mode, Keel uses Docker when it finds a Dockerfile and Cloud Native Buildpacks with heroku/builder:24 otherwise. keel init, keel up, and keel deploy print the selected strategy and reason.

Set the strategy explicitly when it should not depend on the working tree. For example, build: docker fails if the Dockerfile is missing instead of switching to buildpacks. For buildpack builds:

• A buildpack build produces one image for the app. Use command to select Procfile process types such as ["web"] and ["worker"].
• Fargate requires the builder to produce an x86_64 image. Keel pins pack_version for reproducible builds and uses BUILD_GENERAL1_MEDIUM in CodeBuild; keel cost includes that size.

The deploy pipeline

keel deploy separates building, release work, and promotion:

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

1. Preflight — Keel checks the repository and verifies that CodeBuild can reach the selected commit.
2. Build — Services that share a Dockerfile also share a build: Keel builds the image once and tags it for each service. A service with its own dockerfile gets a separate 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. A service still at zero tasks (a fresh environment) is started in the same call that pins the revision.

With no target, keel deploy deploys all services and static sites. It publishes sites after services, inside the same deploy lock, so a frontend is not released before its API. Sites built in CodeBuild use the same commit as the services. You can also name one service or site. Scheduled services use the new revision on their next run and are not watched during deployment.

You can also deploy from the dashboard: D on the Deploys tab (or Deploy in a service's action menu) shows a plan card — commit, branch, services, release command, and every preflight warning individually — and enter confirms; progress streams into the tab. See the Dashboard.

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 the repository CodeBuild clones. Keel does not push to GitHub repositories. If the selected commit is not on the remote, deployment stops and prints the git push command 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.

The console's App Installation field must name the GitHub App installation. Although AWS labels it optional, leaving it blank can produce a connection that reaches AVAILABLE while every CodeBuild project or clone fails. Follow the full Connecting GitHub procedure and troubleshooting checklist.

If a project is created but DOWNLOAD_SOURCE fails with “Failed to get access token,” run keel up with the current build before retrying the deploy. The CodeBuild role needs GetConnectionToken and GetConnection as well as UseConnection; Keel grants both the older codestar-connections and current codeconnections ARN spellings because existing connections retain the name they were created under. This is an infrastructure policy change, so keel deploy alone cannot apply it.

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

Keel clones an existing CodeCommit repository but does not push to or manage it.

source: codecommit with repo unset

Keel creates a <app>-<env> repository as a build input and adds it as the keel git remote. Your team can continue using its existing repository. Before building, keel deploy offers to push the selected commit to the Keel remote:

$ 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.

Each successful deploy records the exact task-definition revision it registered. On an operator session, rollback plans from that history without needing a broad ECS read, then the control plane brokers an update restricted to the selected service and an existing revision.

Unapplied configuration

An apply records the effective merged keel.yml. Other commands compare the current file with that record and print a notice when fields have changed but have not been applied; the dashboard shows the same warning above every tab.

This is especially important for changes a deploy does not apply. keel deploy changes the image while CPU, memory, command, networking, database size, audit recording, and other infrastructure settings remain whatever the last successful keel up or keel infra apply provisioned. Run keel up to converge them.

No record, an unreadable record, or a dropped snapshot is treated as unknown rather than as drift. Values resolved outside keel.yml, such as a GitHub connection ARN, are excluded so a warning does not fire after every command. Set KEEL_NO_DRIFT_CHECK=1 to suppress the CLI notice.

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