Automate Kestra Flow Validation and Deployment with CI/CD

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.

Automate the validation and deployment of your Kestra flows using CI/CD pipelines.

Automate validation and deployment with CI/CD

Continuous integration and delivery (CI/CD) pipelines enable teams to deploy updates automatically and consistently as soon as they are reviewed and merged into a version control system (VCS) like Git. This section covers multiple approaches to building a CI/CD pipeline for Kestra, from kestractl and GitHub Actions to Terraform.

Why use a CI/CD pipeline?

A pipeline deploys the same reviewed flow definitions the same way every time. It removes manual steps, catches invalid flows before they reach production, and keeps a record of what was deployed and when.

CI/CD for Kestra flows

Kestra supports several approaches for automating flow validation and deployment. Choose the one that best fits your environment and tooling preferences.

kestractl

kestractl is the command-line client for the Kestra API. It validates and deploys flows from any CI system, or from your terminal.

kestractl reads its connection settings from environment variables, which suits CI pipelines:

export KESTRACTL_HOST=http://localhost:8080
export KESTRACTL_TOKEN=<your-api-token> # Enterprise Edition and Cloud
# In Open-Source, use basic authentication instead:
# export KESTRACTL_USERNAME=<username>
# export KESTRACTL_PASSWORD=<password>

On your own machine, you can save the same settings once with kestractl config add. See Quick Setup.

Validate and deploy a single flow

kestractl flows validate flow_directory/myflow.yml
kestractl flows deploy flow_directory/myflow.yml --override

Validate and deploy multiple flows

kestractl flows validate flows/
kestractl flows deploy flows/ --namespace prod --override --fail-fast
  • flows validate checks each flow against your Kestra instance and exits non-zero if any flow is invalid, so the pipeline stops before deploying.
  • flows deploy creates flows, and --override updates flows that already exist. Existing flows that aren’t in the directory are kept.
  • --namespace deploys every flow to one namespace. Omit it to keep the namespace written in each flow file, or use --namespace-prefix to prepend a prefix such as staging to each flow’s namespace.

To make the repository the single source of truth and delete flows that aren’t in it, use kestractl flows namespace-sync. For every command and option, see the kestractl reference.

Automate deployments within Kestra

To deploy from Git without an external CI system, run the deployment as a Kestra flow. The SyncFlows and SyncNamespaceFiles tasks read a Git branch and apply its flows and namespace files to Kestra, on a schedule or on every push through a GitHub webhook. See Sync from Git.

Deploy flows with GitHub Actions

Kestra provides official GitHub Actions to validate and deploy flows:

Each action installs and runs kestractl for you. See GitHub Actions for every input.

Example GitHub Actions workflow

name: Kestra CI/CD
on:
push:
branches:
- main
jobs:
prod:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate flows
uses: kestra-io/validate-flows-action-v2@main
with:
directory: ./flows/prod
server: ${{secrets.KESTRA_HOSTNAME}}
user: ${{secrets.KESTRA_USER}}
password: ${{secrets.KESTRA_PASSWORD}}
- name: Deploy prod
uses: kestra-io/deploy-flows-action-v2@main
with:
namespace: prod
directory: ./flows/prod
server: ${{secrets.KESTRA_HOSTNAME}}
user: ${{secrets.KESTRA_USER}}
password: ${{secrets.KESTRA_PASSWORD}}
- name: Deploy prod-marketing
uses: kestra-io/deploy-flows-action-v2@main
with:
namespace: prod.marketing
directory: ./flows/prod.marketing
server: ${{secrets.KESTRA_HOSTNAME}}
user: ${{secrets.KESTRA_USER}}
password: ${{secrets.KESTRA_PASSWORD}}

Deploy flows with GitLab CI and Bitbucket Pipelines

GitLab CI and Bitbucket Pipelines run kestractl in the kestra/kestractl image. See GitLab CI and Bitbucket Pipes for complete pipelines.

Deploy flows with Terraform

With the Kestra Terraform provider, you manage flows as infrastructure as code, alongside the rest of your cloud infrastructure.

This configuration deploys every flow in the flows directory. Each flow’s ID and namespace come from its file:

terraform {
required_providers {
kestra = {
source = "kestra-io/kestra"
version = "~> 2.0"
}
}
}
provider "kestra" {
url = "http://localhost:8080"
api_token = var.kestra_api_token # Enterprise Edition and Cloud
# In Open-Source, use basic authentication instead:
# username = var.kestra_username
# password = var.kestra_password
}
resource "kestra_flow" "flows" {
for_each = fileset(path.module, "flows/*.yml")
content = file(each.value)
}

Then run the following commands:

terraform init # Download the Kestra provider
terraform validate # Validate both the configuration and your flows
terraform apply -auto-approve # Deploy your flows automatically

Next steps

Was this page helpful?