Git Clone

Git Clone
Certified
Clone a Git repository

Clones a repository over HTTP(S) or SSH, optionally checking out a branch, tag, or commit. Defaults to a shallow clone (depth 1) unless a tag or commit is requested; set cloneSubmodules to fetch submodules. Supports repository caching to avoid full re-clones across executions.

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

Examples

Clone a public GitHub repository.

yaml
id: git_clone
namespace: company.team

tasks:
  - id: wdir
    type: io.kestra.plugin.core.flow.WorkingDirectory
    tasks:
      - id: clone
        type: io.kestra.plugin.git.Clone
        url: https://github.com/kestra-io/blueprints
        branch: main

Clone a repository with caching enabled to avoid full re-clones across executions.

yaml
id: git_clone_cached
namespace: company.team

tasks:
  - id: clone
    type: io.kestra.plugin.git.Clone
    url: https://github.com/kestra-io/blueprints
    branch: main
    cache: true
    cacheTtl: PT24H

Clone a private repository from an HTTP server such as a private GitHub repository using a personal access token.

yaml
id: git_clone
namespace: company.team

tasks:
  - id: wdir
    type: io.kestra.plugin.core.flow.WorkingDirectory
    tasks:
      - id: clone
        type: io.kestra.plugin.git.Clone
        url: https://github.com/kestra-io/blueprints
        branch: main
        username: git_username
        password: "{{ secret('GITHUB_ACCESS_TOKEN') }}"

Clone a repository from an SSH server. If you want to clone the repository into a specific directory, you can configure the directory property as shown below.

yaml
id: git_clone
namespace: company.team

tasks:
  - id: wdir
    type: io.kestra.plugin.core.flow.WorkingDirectory
    tasks:
      - id: clone
        type: io.kestra.plugin.git.Clone
        url: git@github.com:kestra-io/kestra.git
        directory: kestra
        privateKey: "{{ secret('SSH_PRIVATE_KEY') }}"
        passphrase: "{{ secret('SSH_PASSPHRASE') }}"

Clone a GitHub repository and run a Python ETL script. Note that the WorkingDirectory task is required so that the Python script shares the same local file system with files cloned from GitHub in the previous task.

yaml
id: git_python
namespace: company.team

tasks:
  - id: file_system
    type: io.kestra.plugin.core.flow.WorkingDirectory
    tasks:
      - id: clone_repository
        type: io.kestra.plugin.git.Clone
        url: https://github.com/kestra-io/examples
        branch: main
      - id: python_etl
        type: io.kestra.plugin.scripts.python.Commands
        dependencies:
          - requests
          - pandas
        commands:
          - python examples/scripts/etl_script.py

Clone then checkout a specific commit (detached HEAD).

yaml
id: git_clone_commit
namespace: company.team

tasks:
  - id: clone_at_sha
    type: io.kestra.plugin.git.Clone
    url: https://github.com/kestra-io/kestra
    commit: 98189392a2a4ea0b1a951cd9dbbfe72f0193d77b

Installation

Our standard Docker images already include this plugin. If you use a -slim image or another setup, install it with the following command:

kestractl plugins get io.kestra.plugin:plugin-git --compatible-for $KESTRA_VERSION

For kestractl, use your Kestra version with --compatible-for, or specify an exact plugin version.

For Kestra CLI, replace LATEST with a specific version or version range to pin the plugin version.

Properties

url *string

Repository URL

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

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

Branch to checkout

Used only when no commit or tag is specified.

cache booleanstring

Defaultfalse

Enable repository caching

When true, caches the .git directory in Kestra internal storage and restores it on subsequent runs, fetching only new commits instead of performing a full clone. Note that only metadata and objects inside .git are cached; working tree files outside .git are not persisted in the cache. Healing corrupted or degraded object caches during incremental fetches is best-effort. Defaults to false.

cacheTtl string

Cache TTL (Time To Live)

After this duration, the repository cache will be invalidated. Defaults to no expiration.

cloneAllBranches booleanstring

Defaulttrue

Clone all branches

When true, clones all remote branches. When false, follows single-branch clone behavior.

cloneSubmodules booleanstring

Clone submodules

Default false; enable to fetch and initialize nested submodules.

commit string

Commit SHA to checkout

Detached HEAD checkout; short SHA allowed. Overrides branch and disables shallow clone.

connectTimeout integerstring

Default10000

HTTP connect timeout (ms)

Default 10000 ms.

depth integerstring

Default1

Shallow clone depth

Defaults to 1. Ignored when commit or tag is set to ensure history is available.

directory string

Target directory

Subdirectory under the working directory where the repo is cloned; defaults to the working directory root.

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)

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.

noTags booleanstring

Defaultfalse

Do not fetch tags

When true, skip fetching tags during clone and fetch fallback.

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.