Builds

Every push to a connected branch triggers a build. The Builds page shows what's deployed, what's queued, and what broke.

How it works

Push code → Keel validates your schema and compiles your functions → if that passes, it deploys. Each environment is tied to a Git branch, so pushing to main might deploy to staging while production deploys to prod.

You can set environments to auto-deploy every successful build, or require manual approval first. Most teams auto-deploy to staging and require approval for production.

The builds list

You'll see every build for the current environment: commit message, author, timestamp, and status. The Live badge shows what's actually serving traffic right now.

Build statuses

Deployment statuses

Build details

Click any build to see what happened. The detail view breaks down each step:

Build steps run first: downloading your code, validating the schema, compiling TypeScript. If your schema has errors or your functions don't compile, it fails here.

Deploy steps run after a successful build: setting up infrastructure, running database migrations, uploading functions. Migration failures are the most common issue at this stage—usually because a schema change conflicts with existing data.

Expand any step to see its logs. Failed steps expand automatically so you can see what went wrong.

Common actions

Approving a deployment — If your environment requires approval, pending builds show up in a separate section. Click one, review the changes, hit Approve.

Retrying a failed build — Sometimes builds fail for transient reasons (network blip, temporary service issue). Click the failed build, then Retry. No need to push a new commit.

Redeploying — Need to restart your application? Click the live build, open the ⋮ menu, select Redeploy. Same code, fresh deployment.

When things go wrong

Schema validation fails — Your .keel files have errors. The log tells you exactly which file and line. Common culprits: typos, missing fields, references to models that don't exist.

Function build fails — TypeScript compilation errors. The logs show the exact errors from the compiler. Usually type mismatches or missing imports.

Migration fails — Your schema change can't be applied to the existing database. This happens when you add a required field without a default, or add a unique constraint that existing data would violate. You'll need to either adjust your schema or fix the data.

Build stuck in queued — Builds run sequentially. If one's stuck, there's probably another build still processing. Check the list for any "Processing" builds.