Git NamespaceSync

Git NamespaceSync
Certified
Sync a Namespace between Kestra and Git

Synchronizes one Namespace 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.

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

Examples

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 *string

Branch to read and write

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

namespace *string

Namespace to sync

Required; syncs only this namespace (no child namespaces).

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.

authorEmail string

Commit author email

authorName string

Commit author name

Defaults to the rendered username when not set.

cloneSubmodules booleanstring

Whether to clone submodules

dryRun booleanstring

Defaultfalse

Plan-only mode

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

gitConfig object

Git config applied after clone

Map of Git config keys and values, applied after clone
Few examples: 
- 'core.fileMode': false -> ignore file permission changes
- 'core.autocrlf': false -> prevent line ending conversion

gitDirectory string

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.

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.

onInvalidSyntax string

DefaultFAIL

Possible Values

SKIPWARNFAIL

Action on invalid resource syntax

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

passphrase string

Passphrase for privateKey

password string

Password or personal access token

When set, pushes use the identity tied to this credential, so authorName and authorEmail become optional.

pluginDefaultsRef string

Reference (ref) of the pluginDefaults to apply to this task.

privateKey string

SSH private key in PEM format

Use an ECDSA/PEM key whose public part is registered on Git. Example: ssh-keygen -t ecdsa -b 256 -m PEM.

protectedNamespaces array

SubTypestring

Default["system"]

Namespaces protected from deletion

Always kept even if whenMissingInSource is DELETE.

sourceOfTruth string

DefaultKESTRA

Possible Values

GITKESTRA

Source of truth for sync

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

strictHostKeyChecking booleanstring

Defaulttrue

Whether to verify the SSH remote server's host key

When true (default), the host key presented by the Git server is verified against knownHosts (if provided) or the system/user known_hosts file, protecting against man-in-the-middle attacks. Only disable this for trusted networks/testing.

url string

Git repository URL

HTTPS or SSH URL used for clone/fetch/push. Supports templating.

username string

Repository username or organization

whenMissingInSource string

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.

Outputs

commitId string

Commit ID pushed (if any)

commitURL string

Commit URL (if any)

diff string

Formaturi

Diff file with planned/applied changes

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

NetBox

Enterprise

Enterprise NetBox tasks to create, update, and query devices, IP addresses, and sites over the NetBox API.

Infrastructure

YouTube

Tasks that interact with the YouTube Data API.

Business

Git NamespaceSyncCertifiedSync a Namespace between Kestra and Git

Git NamespaceSync

More Plugins in this Category

NetBox

YouTube

Git NamespaceSync
Certified
Sync a Namespace between Kestra and Git