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.mdto anykestra.io/docs/*URL for plain Markdown.
Automate the validation and deployment of your Kestra flows using CI/CD pipelines.
If you are on Kestra Enterprise and want to move flows between environments without building a pipeline, see Promote, a UI-first alternative that requires no Git or automation setup.
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.
When flows are deployed 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: trueWhy 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:8080export 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.ymlkestractl flows deploy flow_directory/myflow.yml --overrideValidate and deploy multiple flows
kestractl flows validate flows/kestractl flows deploy flows/ --namespace prod --override --fail-fastflows validatechecks each flow against your Kestra instance and exits non-zero if any flow is invalid, so the pipeline stops before deploying.flows deploycreates flows, and--overrideupdates flows that already exist. Existing flows that aren’t in the directory are kept.--namespacedeploys every flow to one namespace. Omit it to keep the namespace written in each flow file, or use--namespace-prefixto prepend a prefix such asstagingto 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:
validate-flows: validate flows in a directory against a Kestra server.deploy-flows: create or update flows from a directory.deploy-namespace-files: deploy namespace files from a local path.
Each action installs and runs kestractl for you. See GitHub Actions for every input.
Example GitHub Actions workflow
name: Kestra CI/CDon: push: branches: - mainjobs: 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}}You can also authenticate using an API token instead of username and password:
with: server: ${{secrets.KESTRA_HOSTNAME}} apiToken: ${{secrets.KESTRA_API_TOKEN}}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 providerterraform validate # Validate both the configuration and your flowsterraform apply -auto-approve # Deploy your flows automaticallyNext steps
Was this page helpful?