Deployments

Kapable handles the full build-and-deploy pipeline for your apps. Push your code, and Kapable builds, packages, and deploys it to production automatically.

How Deployments Work

The deployment pipeline follows these stages:

1. Requested — A deploy is triggered (manually or via git push)
2. Building — Your app is compiled and packaged
3. Deploying — The built artifact is pushed to the runtime environment
4. Live — Your app is running and serving traffic

If any stage fails, the deployment is marked as failed and the previous version continues running.

Triggering a Deploy

From the Console

1. Open your app in the console
2. Click the Deploy button
3. The deployment starts immediately

From Git

Push to your app's connected repository. Kapable detects the push and triggers a build automatically.

From the API (headless agents)

An sk_org_ org API key can trigger and observe deploys of an existing app — no browser session needed (added 2026-07-14, IMP-2131).

• POST /v1/apps/{app_id}/deploy requires the key to carry the dedicated deploy scope. An org admin mints one via console → org → API keys with scopes ["read","deploy"]. Default read/write keys deliberately cannot trigger deploys.
• GET /v1/apps/{app_id}/deployments and GET /v1/apps/{app_id}/deployments/{deployment_id} need only the read scope — any org key can poll deploy status, including the KAPABLE_ORG_KEY auto-injected into every deployed app's environment.
• Send the key as x-api-key: sk_org_... or Authorization: Bearer sk_org_.... The org is resolved from the key itself — do not send X-Org-Id.
• Poll deployments until status live (not succeeded). App creation still requires a session.

Retry a Failed Deploy

If a deployment fails:

1. Open the app detail page
2. Find the failed deployment in the history
3. Click Retry to re-run the deployment

Retrying uses the same source code but runs a fresh build. This can fix transient issues like network timeouts during dependency installation.

Deployment Statuses

Status	Icon	Meaning
Requested	Grey	Deploy triggered, waiting to start
Building	Blue (pulsing)	App is being compiled and packaged
Deploying	Blue (pulsing)	Artifact is being pushed to production
Live	Green	App is running and healthy
Failed	Red	Something went wrong — check logs
Cancelled	Grey	Deploy was cancelled before completion

Viewing Deployment History

Per-App History

Open any app and scroll to the Deployments section. You'll see a timeline of recent deployments with status, version, duration, and timestamp.

Cross-App History

Navigate to Deployments in the console sidebar to see deployments across all your apps. Use the filters to narrow by app or status.

Environment Variables

Environment variables let you configure your app without changing code. They're injected at build time and runtime.

Setting Variables

1. Open your app → Settings → Environment Variables
2. Add a key-value pair (e.g. DATABASE_URL = postgres://...)
3. Click Save

Changing environment variables triggers a fresh deployment so the new values take effect. See the dedicated Environment Variables guide for built-in variables, limits, and best practices.

Best Practices

• Never commit secrets to your repository — use environment variables instead
• Use descriptive names: STRIPE_API_KEY not KEY1
• Prefix app-specific variables: MYAPP_FEATURE_FLAG
• Kapable automatically sets some variables (like PORT and NODE_ENV)

Build Configuration

Kapable auto-detects your app type and runs the appropriate build steps:

App Type	Detection	Build Command
Node.js	package.json	npm install && npm run build
React	react-scripts in dependencies	npm install && npm run build
Static	index.html in root	No build step

Custom Build Commands

Override the default build command in your app settings if your project uses a non-standard setup.

Zero-Downtime Deploys

Kapable performs rolling deployments to minimise downtime:

1. The new version is started alongside the old one
2. Health checks confirm the new version is ready
3. Traffic is switched to the new version
4. The old version is gracefully shut down

If the new version fails health checks, the deploy is marked as failed and the old version continues serving traffic.

Logs

View build and runtime logs for any deployment:

1. Open the app detail page
2. Click on a specific deployment
3. Build logs show the compilation output
4. Runtime logs show application output after deploy

Logs are available for both successful and failed deployments, helping you diagnose issues.

Next Steps