NamespaceSync

Unidirectional namespace sync between Kestra and Git.

Create/update is driven by 'sourceOfTruth'; delete/keep/fail is driven by 'whenMissingInSource'.

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: system
tasks:
  - id: sync
    type: io.kestra.plugin.git.NamespaceSync
    namespace: system
    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: system
tasks:
  - id: sync
    type: io.kestra.plugin.git.NamespaceSync
    namespace: system
    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

The branch to read from / write to (required).

namespace *string

Target namespace to sync (required).

authorEmail string

The commit author email.

authorName string

The commit author name (defaults to username if null).

cloneSubmodules booleanstring

Whether to clone submodules

dryRun booleanstring

Default false

If true, only compute the plan and output a diff without applying changes.

gitConfig object

Git configuration to apply to the repository

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

Subdirectory inside the repo used to store Kestra code and files; if empty, repo root is used.

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	system	monorepo/system/flows/my-flow.yaml
projectA	company.team	projectA/company.team/flows/my-flow.yaml

onInvalidSyntax string

Default FAIL

Possible Values

SKIPWARNFAIL

Behavior when encountering invalid syntax while syncing.

passphrase string

The passphrase for the privateKey

password string

The password or Personal Access Token (PAT) -- when you authenticate the task with a PAT, any flows or files pushed to Git from Kestra will be pushed from the user associated with that PAT. This way, you don't need to configure the commit author (the authorName and authorEmail properties).

privateKey string

PEM-format private key content that is paired with a public key registered on Git

To generate an ECDSA PEM format key from OpenSSH, use the following command: ssh-keygen -t ecdsa -b 256 -m PEM. You can then set this property with your private key content and put your public key on Git.

protectedNamespaces array

SubType string

Default ["system"]

Namespaces protected from deletion regardless of policies.

sourceOfTruth string

Default KESTRA

Possible Values

GITKESTRA

Select the source of truth.

trustedCaPemPath string

Optional path to a PEM-encoded CA certificate to trust (in addition to the JVM default truststore)

Equivalent to git config http.sslCAInfo <path>. Use this for self-signed/internal CAs.

url string

The URI to clone from

username string

The username or organization

whenMissingInSource string

Default DELETE

Possible Values

DELETEKEEPFAIL

Behavior when an object is missing from the selected source of truth.

Outputs

commitId string

ID of the commit pushed (if any).

commitURL string

URL to the commit (if any).

diff string

Format uri

A file containing all changes applied (or not in case of dry run) to/from Git.

​Namespace​Sync

NamespaceSync