Streamline Kestra Flow Deployment with Bitbucket Pipes

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.

How to use Bitbucket Pipes to create a CI/CD pipeline for your Kestra flows.

Automate Kestra deployments with Bitbucket Pipes

With the kestractl Docker image, you can validate and deploy flows from Bitbucket repositories through Bitbucket Pipelines.

Example pipeline

This bitbucket-pipelines.yml validates the flows in the flows/ directory on every branch. On main, it also deploys them to the prod namespace:

image: kestra/kestractl:latest
definitions:
steps:
- step: &validate
name: Validate Kestra flows
script:
- kestractl flows validate flows/
pipelines:
default:
- step: *validate
branches:
main:
- step: *validate
- step:
name: Deploy Kestra flows
deployment: production
script:
- kestractl flows deploy flows/ --namespace prod --override --fail-fast
  • flows validate checks each flow against your Kestra instance and fails the step 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.
  • --fail-fast stops at the first flow that fails to deploy.

Configure the connection

kestractl reads its connection settings from environment variables, so the pipeline doesn’t pass credentials on the command line. Define these variables in Bitbucket under Repository settings > Repository variables, or per environment under Deployments so that the production deployment can target a different Kestra instance:

VariableValue
KESTRACTL_HOSTURL of your Kestra instance, such as https://kestra.example.com
KESTRACTL_TENANTTenant ID. Optional in Open-Source, which uses main
KESTRACTL_TOKENAn API token (Enterprise Edition and Cloud)
KESTRACTL_USERNAME and KESTRACTL_PASSWORDBasic authentication credentials, if you don’t use an API token

Mark KESTRACTL_TOKEN and KESTRACTL_PASSWORD as Secured so Bitbucket masks them in build logs. Never print them in a step.

The Bitbucket runner must be able to reach your Kestra instance. For a Kestra instance on a private network, use a self-hosted runner.

Tips

  • Pin the image to a release tag, kestra/kestractl:X.Y.Z, so that a new kestractl version doesn’t change your pipeline unexpectedly.
  • For more commands, such as deploying namespace files with kestractl nsfiles upload, see the kestractl reference.

Was this page helpful?