Git NamespaceSync

Git NamespaceSync

Certified

Sync a Namespace between Kestra and Git

Synchronizes one Namespace (optionally its child namespaces via includeChildNamespaces) using a namespace-first folder layout in Git. Syncs flows, namespace files, apps, unit tests, and custom blueprints. Defaults to Kestra as source of truth; deletions follow whenMissingInSource while protectedNamespaces are never removed. Enable dryRun to preview the diff without applying it. The flow containing this task does not need to live in the same namespace as the one being synced. Flows saved as drafts are not synced to Git.

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

Sync a namespace using Git as the source of truth (destructive).

yaml
id: git_namespace_sync
namespace: company.ops
tasks:
  - id: sync
    type: io.kestra.plugin.git.NamespaceSync
    namespace: company.ops
    sourceOfTruth: GIT
    whenMissingInSource: DELETE
    protectedNamespaces:
      - system
    url: https://github.com/fdelbrayelle/plugin-git-qa
    username: fdelbrayelle
    password: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
    branch: main
    gitDirectory: kestra

Sync a namespace using Kestra as source of truth (additive).

yaml
id: kestra_namespace_sync
namespace: company.ops
tasks:
  - id: sync
    type: io.kestra.plugin.git.NamespaceSync
    namespace: company.ops
    sourceOfTruth: KESTRA
    whenMissingInSource: KEEP
    protectedNamespaces:
      - system
    url: https://github.com/fdelbrayelle/plugin-git-qa
    username: fdelbrayelle
    password: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
    branch: dev
    # gitDirectory omitted -> repository root
    onInvalidSyntax: WARN
    # dryRun omitted
Properties

Branch to read and write

Required. Do not prefix with origin/ or refs/heads/.

Namespace to sync

Required; syncs only this namespace unless includeChildNamespaces is true.

  • sourceOfTruth: GIT — if the namespace does not exist in the target Kestra instance it is created automatically, making this the right choice when deploying to a fresh instance (e.g. preprod → Git → prod).
  • sourceOfTruth: KESTRA — if the namespace does not exist or is empty the task completes with an empty diff (no error). Create the namespace manually in Kestra first if you want to populate it before syncing to Git.

Kestra API authentication

Definitions
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.

Commit author email

Commit author name

Defaults to the rendered username when not set.

Clone submodules

Default false; enable to fetch and initialize nested submodules.

Default10000

HTTP connect timeout (ms)

Default 10000 ms.

Defaultfalse

Plan-only mode

When true, computes the diff and outputs it without applying changes.

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)

Base folder for Kestra files

This is the base folder in your Git repository where Kestra will look for code and files. If you don't set it, the repo root will be used. Inside that folder, Kestra always expects a structure like /flows, /files, etc.

gitDirectory namespace Expected Git path
(not set) company company/flows/my-flow.yaml
monorepo company.ops monorepo/company.ops/flows/my-flow.yaml
projectA company.team projectA/company.team/flows/my-flow.yaml

Note: a dotted namespace such as company.team maps to a folder literally named company.team, not to a nested company/team path.

Defaultfalse

Include child namespaces

Default false. When true, also syncs every descendant namespace of namespace (blueprints stay tenant-scoped).

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.

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.

Disable proxy for HTTP

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

DefaultFAIL
Possible Values
SKIPWARNFAIL

Action on invalid resource syntax

Defaults to FAIL. Use WARN or SKIP to continue when parsing issues occur.

Passphrase for privateKey

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.

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.

SubTypestring
Default["system"]

Namespaces protected from deletion

Always kept even if whenMissingInSource is DELETE.

Default60000

HTTP read timeout (ms)

Default 60000 ms.

DefaultKESTRA
Possible Values
GITKESTRA

Source of truth for sync

Defaults to KESTRA. Choose GIT to make the repository authoritative.

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.

Extra trusted CA PEM path

Optional PEM-encoded CA bundle added to the JVM truststore; equivalent to git config http.sslCAInfo <path> for self-signed or internal CAs.

Repository URL

HTTP(S) or SSH URI used for clone and push operations.

Username or organization

Used for HTTP basic authentication and as a fallback commit author.

DefaultDELETE
Possible Values
DELETEKEEPFAIL

Action when item missing in source

Default DELETE. Determines whether missing resources are deleted, kept, or cause the task to fail.

Commit ID pushed (if any)

Commit URL (if any)

Formaturi

Diff file with planned/applied changes

Points to the ion diff stored in internal storage; includes dry-run plans.

More Plugins in this Category

Azure (EE)
Azure
Enterprise

Tasks that integrate Microsoft Azure services into Kestra enterprise workflows.

CloudDataInfrastructure

7 tasks

Elasticsearch
Elasticsearch

Tasks that query and write to Elasticsearch clusters for search, indexing, bulk ingestion, and ES|QL.

DataInfrastructure

8 tasks

3 blueprints