Configure GitLab CI Pipelines to Deploy Kestra Flows

Table of Contents

Use GitLab CI to automate the validation and deployment of your Kestra flows.

Automate Kestra deployments with GitLab CI

GitLab CI lets you define pipelines in a .gitlab-ci.yml file to automate tests, builds, and deployments. With Kestra, you can validate and deploy flows directly from your pipeline using the Kestra CLI.

For flows managed through CI/CD, add the system.readOnly label set to "true" so the UI editor is disabled and production configurations stay immutable. This is especially recommended for critical production flows:

labels:
  system.readOnly: true

Your GitLab runner must be able to reach your Kestra instance.

If your Kestra server is publicly accessible, a shared GitLab runner is sufficient.
If your Kestra server is private, use a self-hosted runner with network access to Kestra.

Example pipeline

The example below defines two stages — validate and deploy — and runs the Kestra CLI in an official Kestra image. Validation runs first; if it succeeds, the deploy stage updates a target namespace with the flows from your repository.

stages:
  - validate
  - deploy

default:
  image:
    name: kestra/kestra:latest
    entrypoint: [""]

variables:
  KESTRA_HOST: https://kestra.io/

validate:
  stage: validate # Validate flows server-side
  script:
    - /app/kestra flow validate ./kestra/flows --server ${KESTRA_HOST} --api-token $KESTRA_API_TOKEN

deploy:
  stage: deploy
  script:
    - /app/kestra flow namespace update my_namespace ./kestra/flows/prod --server ${KESTRA_HOST} --api-token $KESTRA_API_TOKEN

Authentication options:

Use the --api-token flag (as shown).
Use basic auth with --user=USERNAME:PASSWORD if API tokens are not available.

Tips

Pin the Docker image (e.g., kestra/kestra:1.0.x) to avoid unexpected CLI changes.

TerraformTerraform for Kestra – Manage Resources as Code

Was this page helpful?