Git SyncFlows

Git SyncFlows
Certified
Sync flows from Git

Imports flows from a Git branch into targetNamespace, optionally traversing child namespaces. Can rewrite namespaces to targetNamespace, delete missing flows when delete is true, and emit a diff on dry-run. See Output.unresolvedFlowLookups for a signal that some flows may be misreported in the diff because their Kestra state could not be resolved.

yaml
type: io.kestra.plugin.git.SyncFlows

Examples

Sync flows from a Git repository. This flow can run either on a schedule (using the Schedule trigger) or anytime you push a change to a given Git branch (using the Webhook trigger).

yaml
id: sync_flows_from_git
namespace: company.ops

tasks:
  - id: git
    type: io.kestra.plugin.git.SyncFlows
    gitDirectory: flows
    targetNamespace: git
    includeChildNamespaces: true
    delete: true
    url: https://github.com/kestra-io/flows
    branch: main
    username: git_username
    password: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
    dryRun: true

triggers:
  - id: every_full_hour
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "0 * * * *"

Sync all flows and scripts for selected namespaces from Git to Kestra every full hour. Note that this is a System Flow, so make sure to adjust the Scope to SYSTEM in the UI filter to see this flow or its executions.

yaml
id: git_sync
namespace: company.ops

tasks:
  - id: sync
    type: io.kestra.plugin.core.flow.Loop
    values: ["company", "company.team", "company.analytics"]
    tasks:
      - id: flows
        type: io.kestra.plugin.git.SyncFlows
        targetNamespace: "{{ item.value }}"
        gitDirectory: "{{'flows/' ~ item.value}}"
        includeChildNamespaces: false
        username: anna-geller
        url: https://github.com/anna-geller/product
        password: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
        branch: main
        dryRun: false

      - id: scripts
        type: io.kestra.plugin.git.SyncNamespaceFiles
        namespace: "{{ item.value }}"
        gitDirectory: "{{'scripts/' ~ item.value}}"
        username: anna-geller
        url: https://github.com/anna-geller/product
        password: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
        branch: main
        dryRun: false

triggers:
  - id: every_full_hour
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "0 * * * *"

Properties

targetNamespace *string

Target namespace

Flows are rewritten to this namespace (and nested namespaces when applicable).

assets

Assets this task consumes as inputs or produces as outputs, for lineage tracking and the asset graph (Enterprise Edition). A flow declaring this property on a task is rejected in the open-source edition.

Definitions

io.kestra.core.models.assets.AssetsDeclaration

assetFailureBehaviorstring

Possible Values

IGNOREFAILWARN

Asset failure behavior

Behavior applied to the task state when a declared asset fails to render, emit, or be persisted (e.g. a lock conflict): FAIL escalates it to FAILED, WARN (default) warns it if it would otherwise succeed, IGNORE leaves the state untouched.

enableAutobooleanstring

Whether to auto-register assets referenced dynamically at runtime that are not statically declared in inputs or outputs.

inputsarray

The assets consumed as inputs.

io.kestra.core.models.assets.AssetIdentifier

id*string

Min length1

typestring

outputs

The assets produced as outputs.

io.kestra.plugin.ee.assets.Dataset

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.plugin.ee.assets.File

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.plugin.ee.assets.Table

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.plugin.ee.assets.VM

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.core.models.assets.External

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.core.models.assets.Custom

id*string

Min length1

Max length150

type*string

Min length1

Custom asset type

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

auth

Kestra API authentication

Definitions

io.kestra.plugin.git.shared.AbstractCloningTask-Auth

apiTokenstring

API token for authentication.

autobooleanstring

Defaulttrue

Automatically retrieve the URL and the credentials from Kestra's configuration if available

Can be configured globally in the Kestra configuration file:

Set kestra.tasks.sdk.authentication.url for the API URL
Set kestra.tasks.sdk.authentication.api-token for API token auth
Set kestra.tasks.sdk.authentication.username and kestra.tasks.sdk.authentication.password for HTTP Basic auth The Enterprise Edition also allows an administrator to set these defaults at the namespace or the tenant level. Set this to false without any credentials to call a Kestra API that requires no authentication.

passwordstring

Password for HTTP Basic authentication.

usernamestring

Username for HTTP Basic authentication.

branch string

Defaultmain

Branch to sync

Defaults to main.

cloneSubmodules booleanstring

Clone submodules

Default false; enable to fetch and initialize nested submodules.

connectTimeout integerstring

Default10000

HTTP connect timeout (ms)

Default 10000 ms.

delete booleanstring

Defaultfalse

Delete flows missing in Git

Default false to avoid destructive syncs. When true (and especially with includeChildNamespaces), removes flows not present in Git.

dryRun booleanstring

Defaultfalse

Dry run only

When true, writes a diff without applying changes to Kestra.

failOnMissingBranch booleanstring

Defaulttrue

Fail if branch missing

Default true. If false, falls back to creating the requested branch from the repository's default branch when the rendered branch does not exist on the remote. This means the sync then reads content from the default branch instead of the requested one, and with delete set to true it can delete namespace content that only exists on the requested branch.

failOnMissingDirectory booleanstring

Defaulttrue

Fail if git directory missing

Default true. If false, skips when the rendered gitDirectory path does not exist.

gitConfig object

Git configuration overrides

Map of git config keys and values applied after clone, e.g.:

core.fileMode: false (ignore permission flips)
core.autocrlf: false (preserve line endings)

gitDirectory string

Default_flows

Git directory for flows

Relative path containing flow YAML; defaults to _flows. Subdirectories map to child namespaces when includeChildNamespaces is true.

ignoreInvalidFlows booleanstring

Defaultfalse

Ignore invalid flows

If true, skips flows that fail validation instead of failing the task.

includeChildNamespaces booleanstring

Defaultfalse

Include child namespaces

Default false. When true, subdirectories under gitDirectory are synced to corresponding child namespaces.

kestraUrl string

Kestra API URL

URL of the Kestra server API. If not set, the URL of the default SDK authentication is used, set with the kestra.tasks.sdk.authentication.url configuration property, or at the namespace or the tenant level on the Enterprise Edition. It then falls back to the kestra.url configuration property, and finally to http://localhost: 8080.

knownHosts string

Known hosts file content used for SSH host key verification

OpenSSH known_hosts-formatted content used to verify the remote server's SSH host key. If not set, the system/user known_hosts file is used. Only relevant when strictHostKeyChecking is true.

noProxy booleanstring

Disable proxy for HTTP

When true, forces direct connections instead of using the JVM proxy settings.

passphrase string

Passphrase for privateKey

password string

Password or personal access token

Supplies HTTP credentials. When a PAT is used, pushes are recorded under that PAT’s user without needing authorName and authorEmail.

**GitHub PAT permissions required: **

Fine-grained PAT: Contents: Read (clone/fetch) or Contents: Read and Write (push), plus Metadata: Read (mandatory base permission). Add Workflows: Read and Write when pushing .github/workflows/ files.
Classic PAT: repo scope covers all read/write operations; add workflow when pushing workflow files.

privateKey string

PEM private key

PEM-formatted private key matching a public key registered on the Git server. Generate with ssh-keygen -t ecdsa -b 256 -m PEM.

readTimeout integerstring

Default60000

HTTP read timeout (ms)

Default 60000 ms.

strictHostKeyChecking booleanstring

Whether to verify the SSH remote server's host key

When enabled, the host key presented by the Git server is verified against knownHosts (if provided) or the system/user known_hosts file. Disabling it exposes the connection to man-in-the-middle attacks (CWE-297). Set knownHosts alongside this property for a hardened setup. The default differs by edition: disabled (false) on Kestra OSS, enabled (true) on Kestra Enterprise Edition.