Push Flows and Namespace Files from Kestra to Git

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.

Commit flows and namespace files that you build in the Kestra UI to a Git repository.

The PushFlows and PushNamespaceFiles tasks export resources from a namespace and push them to a Git branch. Use them when your team builds and tests flows in the UI, for example in a development namespace, and wants a reviewed history in Git. To go the other way, from Git into Kestra, see Sync from Git.

Before you begin

  • A Git repository and a personal access token (PAT) with write access to it. Store the PAT as a secret, for example GITHUB_ACCESS_TOKEN.
  • Credentials for the Kestra API. Both tasks read resources through the API, so on an instance with authentication they need either task-level auth (and kestraUrl if the API isn’t reachable at the default URL) or default credentials configured with kestra.tasks.sdk.authentication.*, or at the namespace or tenant level in Enterprise Edition. See SDK authentication.

Push flows

This flow pushes every flow in company.team to the develop branch. With dryRun: true, it computes the changes without committing anything:

id: push_flows_to_git
namespace: company.ops
tasks:
- id: commit_and_push
type: io.kestra.plugin.git.PushFlows
url: https://github.com/my-org/kestra-flows
username: git_username
password: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
branch: develop
sourceNamespace: company.team
gitDirectory: flows
commitMessage: "Push flows from company.team"
dryRun: true

Run the flow and open the task’s Outputs tab. The flows output is a file with one row per added, changed, or deleted file in Git. Check it, then set dryRun: false and run the flow again. The task commits and pushes the changes, and its commitId and commitURL outputs point to the new commit.

Each flow is written to <gitDirectory>/<flowId>.yml. If branch doesn’t exist yet, the task creates it, so you can push to a feature branch and open a pull request for review.

Choose which flows to push

  • flows takes one or more glob patterns matched against flow IDs, such as etl_*. The default ** matches every flow. To push only the flow that runs the task, use flows: "{{ flow.id }}".
  • Draft flows are never pushed.
  • targetNamespace rewrites each flow’s top-level namespace before the push, for example from company.team to company.prod, so the files in Git are ready to sync into production. Nested namespace properties, such as a Subflow’s, keep their value.

Include child namespaces

Set includeChildNamespaces: true to also push flows from namespaces below sourceNamespace. Each child namespace becomes a subfolder named after the part of the namespace below sourceNamespace:

FlowNamespacePath in Git (gitDirectory: flows)
hello_worldcompany.teamflows/hello_world.yml
hello_world_1company.team.tutorialflows/tutorial/hello_world_1.yml
reportcompany.team.tutorial.dailyflows/tutorial/daily/report.yml

Push namespace files

PushNamespaceFiles works the same way for namespace files. This flow pushes the Python scripts of company.team to the _files directory:

id: push_files_to_git
namespace: company.ops
tasks:
- id: commit_and_push
type: io.kestra.plugin.git.PushNamespaceFiles
url: https://github.com/my-org/kestra-flows
username: git_username
password: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
branch: develop
namespace: company.team
files:
- "**.py"
gitDirectory: _files
commitMessage: "Push scripts from company.team"
dryRun: true
  • files takes glob patterns matched against each file’s path from the namespace root. The default ** matches every file.
  • The dry-run diff is in the task’s files output.
  • With includeChildNamespaces: true, files from each child namespace go under a folder named after the full namespace, such as _files/company.team.tutorial/.
  • Set errorOnMissing: true to fail the task when no file matches.

Push one folder of a namespace

Use namespaceDirectory to push only the files under one folder of the namespace. The folder prefix is removed from the Git path, so a file at /shared-scripts/helpers/parse.py in the namespace lands at scripts/helpers/parse.py with this configuration:

id: push_shared_scripts
namespace: company.ops
tasks:
- id: commit_and_push
type: io.kestra.plugin.git.PushNamespaceFiles
url: https://github.com/my-org/kestra-flows
username: git_username
password: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
branch: develop
namespace: company.team
gitDirectory: scripts
namespaceDirectory: /shared-scripts
files:
- "shared-scripts/**"
commitMessage: "Push shared scripts"

The files patterns still match the full path from the namespace root, not the path inside namespaceDirectory. A SyncNamespaceFiles task with the same gitDirectory and namespaceDirectory is the exact inverse, so syncing and then pushing produces no changes.

Deleted resources

By default, delete is true: when a flow or file no longer exists in Kestra, the push removes its file from Git. Only files the task manages are affected, such as files under gitDirectory, or under namespaceDirectory for a scoped push. Set delete: false to keep files in Git after you delete them in Kestra.

To push only deletions, set pushMode: DELETE_ONLY. The task removes files for resources that no longer exist and leaves every other file unchanged, even if the resource changed since the last push.

Push on a schedule

Add a Schedule trigger to push changes regularly. This flow pushes every flow in company.team and its child namespaces every day at 17:00:

id: push_flows_daily
namespace: company.ops
tasks:
- id: commit_and_push
type: io.kestra.plugin.git.PushFlows
url: https://github.com/my-org/kestra-flows
username: git_username
password: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
branch: develop
sourceNamespace: company.team
includeChildNamespaces: true
gitDirectory: flows
commitMessage: "Daily push from company.team"
triggers:
- id: daily
type: io.kestra.plugin.core.trigger.Schedule
cron: "0 17 * * *"

Git doesn’t order concurrent pushes to the same branch. If several flows or people push at the same time, a push can fail or conflict. Run pushes one at a time, for example with a concurrency limit of 1, or push to separate branches.

Defaults

PropertyPushFlows defaultPushNamespaceFiles default
branchmain, created if missingmain, created if missing
gitDirectory_flows_files
Source namespacesourceNamespace: the namespace of the flow that runs the tasknamespace: the namespace of the flow that runs the task
includeChildNamespacesfalsefalse
deletetruetrue
dryRunfalsefalse

For every property, see the PushFlows and PushNamespaceFiles plugin pages.

Was this page helpful?