Configure GitLab CI Pipelines to Deploy Kestra Flows

For the complete documentation index, see llms.txt. For a full content snapshot, see llms-full.txt. Append .md to any kestra.io/docs/* URL for plain Markdown.

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


Example pipeline

The example below defines two stages, validate and deploy, and runs kestractl from the kestra/kestractl image. Validation runs first; if it succeeds on the default branch, the deploy stage creates or updates the flows from your repository in the prod namespace.

stages:
- validate
- deploy
default:
image:
name: kestra/kestractl:latest
entrypoint: [""]
variables:
KESTRACTL_HOST: https://your-kestra-host
validate:
stage: validate
script:
- kestractl flows validate ./kestra/flows
deploy:
stage: deploy
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
script:
- kestractl flows deploy ./kestra/flows/prod --namespace prod --override --fail-fast
  • entrypoint: [""] clears the image’s kestractl entrypoint so GitLab can run the script commands in a shell.
  • flows validate checks each flow against your Kestra instance and fails the job if any flow is invalid.
  • flows deploy creates the flows, and --override updates flows that already exist. --namespace prod deploys every flow to prod; omit it to keep the namespace written in each flow file.

Authentication

kestractl reads its credentials from environment variables. Add them in GitLab under Settings > CI/CD > Variables, and mark the secret ones as Masked and Protected:

  • KESTRACTL_TOKEN: an API token (Enterprise Edition and Cloud).
  • KESTRACTL_USERNAME and KESTRACTL_PASSWORD: basic authentication credentials, if API tokens aren’t available.
  • KESTRACTL_TENANT: your tenant ID. Optional in Open-Source, which uses main.

Don’t write credentials in .gitlab-ci.yml.


Tips

  • Pin the image to a release tag, kestra/kestractl:X.Y.Z, to avoid unexpected CLI changes.
  • For more commands, such as deploying namespace files with kestractl nsfiles upload, see the kestractl reference.

Was this page helpful?