Deploy to Kubernetes from any CI with Wodby

This guide starts from an app that already exists in Wodby and has a buildable app service. The CI provider checks out the repository, then Wodby CLI creates the build from the app service ID, builds and releases images, and deploys them to the selected app instance.

When to use Custom CI

Use Custom CI for unsupported CI systems, self-managed runners, or cases where Wodby should not connect to the CI provider API. Wodby accepts the provider value sent by the CLI, but it does not poll the provider for status and cannot trigger or rerun provider jobs from the dashboard.

What you need

• A Wodby app instance using Custom CI as its CI integration.
• A buildable app service. A linked Git repository is optional for Custom CI because the external pipeline supplies the checkout.
• A Wodby API key from User API keys.
• The buildable app service ID from the service overview in Wodby.
• A CI runner that can run Docker builds. If it uses Docker-in-Docker, initialize Wodby CLI with --dind.

Set up the app in Wodby

In the new app form, choose Custom CI as the CI integration. On the build source step, use Connect git repository for the buildable service only when you want repository metadata in Wodby. Without a linked repository, Wodby trusts the git metadata submitted by the CLI from the CI checkout.

Add CI variables

Add WODBY_API_KEY as a secret in your CI provider. Add WODBY_APP_SERVICE_ID as a variable. If your CI system exposes a run ID and build number, map them to CI_BUILD_ID and CI_BUILD_NUMBER. The script below falls back to common generic values when those variables are absent.

Add the pipeline script

Put this script in your CI job after the repository checkout:

#!/usr/bin/env sh
set -eu

: "${WODBY_API_KEY:?Set WODBY_API_KEY in your CI secret variables.}"
: "${WODBY_APP_SERVICE_ID:?Set WODBY_APP_SERVICE_ID to the buildable app service ID.}"

CI_BUILD_NUMBER="${CI_BUILD_NUMBER:-${BUILD_NUMBER:-$(date +%s)}}"
CI_COMMIT_SHORT="$(git rev-parse --short HEAD 2>/dev/null || echo manual)"
CI_BUILD_ID="${CI_BUILD_ID:-${BUILD_ID:-$CI_COMMIT_SHORT-$CI_BUILD_NUMBER}}"

if ! command -v wodby >/dev/null 2>&1; then
  curl -fsSL https://api.wodby.com/v1/get/cli | sh
fi

wodby ci init \
  --provider unknown \
  --build-id "$CI_BUILD_ID" \
  --build-num "$CI_BUILD_NUMBER" \
  "$WODBY_APP_SERVICE_ID"

wodby ci run -- npm ci
wodby ci build
wodby ci release
wodby ci deploy

Docker-in-Docker runners

If your CI job builds through Docker-in-Docker, replace the init command with:

wodby ci init \
  --dind \
  --provider unknown \
  --build-id "$CI_BUILD_ID" \
  --build-num "$CI_BUILD_NUMBER" \
  "$WODBY_APP_SERVICE_ID"

Secret build arguments

If your app uses secret build-scoped environment variables, define matching secret variables in the CI provider. Wodby CLI forwards secret build args from the CI environment instead of storing their values in the local build config.

# Example: your Dockerfile declares ARG PRIVATE_NPM_TOKEN
# Define PRIVATE_NPM_TOKEN as a secret in your CI provider.
wodby ci build

What Wodby tracks

Wodby CLI sends git ref, commit SHA, author, commit message, build ID, build number, and the provider value to Wodby. For unsupported providers, use --provider unknown. If the job runs in a known provider such as GitHub Actions, GitLab CI, or CircleCI, you can also let the CLI send the detected provider value.

The external CI job must call wodby ci deploy after images are released. If the job fails before deployment, Wodby does not receive a provider status update for Custom CI.

Troubleshooting

• If initialization fails, confirm WODBY_API_KEY is available to the job and has not been filtered by branch or environment rules.
• If Wodby cannot create the build, check that WODBY_APP_SERVICE_ID points to a buildable app service.
• If the runner cannot build images, use a runner with Docker access or initialize with --dind when the provider uses Docker-in-Docker.
• If the app remains undeployed, confirm the job reached wodby ci release and wodby ci deploy.

For provider behavior, see the Custom CI provider docs. For the generic third-party CI flow, see the third-party CI docs. For command details, see the Wodby CLI docs.