Skip to main content
The Git Resolver fetches Tekton resources from git repositories using either anonymous cloning or authenticated API access.

​
Resolver Type

This resolver responds to type git.

​
Parameters

​
url
string
URL of the repo to fetch and clone anonymously. Either url, or repo (with org) must be specified, but not both.Example: https://github.com/tektoncd/catalog.git
​
repo
string
The repository to find the resource in. Either url, or repo (with org) must be specified, but not both.Example: pipeline, test-infra
​
org
string
The organization to find the repository in. Default can be set in configuration.Example: tektoncd, kubernetes
​
revision
string
Git revision to checkout. This can be commit SHA (SHA-1 or SHA-256), branch, or tag.Example: aeb957601cf41c012be462827053a21a420befca, main, v0.38.2
​
pathInRepo
string
required
Where to find the file in the repo.Example: task/golang-build/0.3/golang-build.yaml
​
token
string
Optional secret name to fetch the API token from. Defaults to configuration from global configmap.Example: secret-name
​
tokenKey
string
default:"token"
Optional key in the token secret to fetch the token from.
​
gitToken
string
Optional secret name for git clone authentication. When empty, uses anonymous cloning.Example: secret-gitauth-token
​
gitTokenKey
string
default:"token"
Optional key in the gitToken secret to fetch the token from.
​
serverURL
string
Optional server URL for API operations.Example: https://github.mycompany.com
​
scmType
string
Optional SCM type for API operations.Options: github, gitlab, gitea, bitbucketcloud, bitbucketserver
​
cache
string
default:"auto"
Controls caching behavior for the resolved resource.Options: always, never, auto

​
Requirements

  • A cluster running Tekton Pipeline v0.41.0 or later
  • Built-in remote resolvers installed
  • The enable-git-resolver feature flag set to true in the resolvers-feature-flags ConfigMap
  • Beta features enabled

​
Configuration

The Git Resolver uses the git-resolver-config ConfigMap in the tekton-pipelines-resolvers namespace.

​
Configuration Options

default-revision

Default git revision if none specified (e.g., main)

fetch-timeout

Maximum time for git clone operations (e.g., 1m, 2s)

default-url

Default repository URL for anonymous cloning

scm-type

SCM provider type for authenticated API (e.g., github, gitlab)

server-url

SCM provider base URL for authenticated API

api-token-secret-name

Kubernetes secret containing the SCM API token

api-token-secret-key

Key within the token secret containing the token

default-org

Default organization for repositories

​
Caching Options

Cache ValueDescription
alwaysAlways cache resolved resources
neverNever cache resolved resources
autoCache only when revision is a commit hash (default)
Configure default cache mode in the git-resolver-config ConfigMap: 
apiVersion: v1
kind: ConfigMap
metadata:
  name: git-resolver-config
  namespace: tekton-pipelines-resolvers
data:
  default-cache-mode: "auto"

​
Resolution Modes

The Git Resolver supports two modes:

​
Git Clone Mode

Uses the go-git library to clone repositories. Supports anonymous and authenticated cloning. Advantages:
  • Not subject to API rate limits
  • Higher throughput for repeated access
  • Supports both anonymous and authenticated access
Limitations:
  • Clones entire repository in memory
  • Inefficient for large repositories
  • Some commits may not be fetchable without branch/tag refs

​
Authenticated API Mode

Fetches individual files via SCM provider APIs (GitHub, GitLab, Gitea, BitBucket). Advantages:
  • Supports private repositories
  • Fetches only the required file
  • Efficient for large repositories
Limitations:
  • Subject to API rate limits
  • Requires authentication token

​
Usage Examples

​
Task Resolution with Git Clone

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: git-clone-demo-tr
spec:
  taskRef:
    resolver: git
    params:
    - name: url
      value: https://github.com/tektoncd/catalog.git
    - name: revision
      value: main
    - name: pathInRepo
      value: task/git-clone/0.6/git-clone.yaml

​
Task Resolution with Authenticated Git Clone

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: git-clone-auth-tr
spec:
  taskRef:
    resolver: git
    params:
    - name: url
      value: https://github.com/myorg/private-repo.git
    - name: revision
      value: main
    - name: pathInRepo
      value: tasks/my-task.yaml
    - name: gitToken
      value: git-auth-secret
    - name: gitTokenKey
      value: token

​
Task Resolution with Authenticated API

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: git-api-demo-tr
spec:
  taskRef:
    resolver: git
    params:
    - name: org
      value: tektoncd
    - name: repo
      value: catalog
    - name: revision
      value: main
    - name: pathInRepo
      value: task/git-clone/0.6/git-clone.yaml

​
Task Resolution with Custom SCM Provider

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: git-custom-scm-tr
spec:
  taskRef:
    resolver: git
    params:
    - name: org
      value: tektoncd
    - name: repo
      value: catalog
    - name: revision
      value: main
    - name: pathInRepo
      value: task/git-clone/0.6/git-clone.yaml
    - name: token
      value: my-secret-token
    - name: tokenKey
      value: token
    - name: scmType
      value: github
    - name: serverURL
      value: https://ghe.mycompany.com

​
Pipeline Resolution

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: git-clone-demo-pr
spec:
  pipelineRef:
    resolver: git
    params:
    - name: url
      value: https://github.com/tektoncd/catalog.git
    - name: revision
      value: main
    - name: pathInRepo
      value: pipeline/simple/0.1/simple.yaml
  params:
  - name: name
    value: Ranni

​
Multiple Git Provider Configurations

You can configure multiple Git providers in the same ConfigMap using unique key prefixes: 
apiVersion: v1
kind: ConfigMap
metadata:
  name: git-resolver-config
  namespace: tekton-pipelines-resolvers
data:
  # Default configuration
  fetch-timeout: "1m"
  default-url: "https://github.com/tektoncd/catalog.git"
  default-revision: "main"
  
  # GitHub Enterprise configuration
  ghe.scm-type: "github"
  ghe.server-url: "https://github.enterprise.com"
  ghe.api-token-secret-name: "ghe-token"
  ghe.api-token-secret-key: "token"
  ghe.default-org: "myorg"
  
  # GitLab configuration
  gitlab.scm-type: "gitlab"
  gitlab.server-url: "https://gitlab.company.com"
  gitlab.api-token-secret-name: "gitlab-token"
  gitlab.api-token-secret-key: "pat"
  gitlab.default-org: "engineering"
Reference a specific configuration using the configKey parameter: 
apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: git-ghe-tr
spec:
  taskRef:
    resolver: git
    params:
    - name: org
      value: myorg
    - name: repo
      value: myrepo
    - name: pathInRepo
      value: tasks/build.yaml
    - name: configKey
      value: ghe

​
ResolutionRequest Status

The ResolutionRequest.Status.RefSource field captures source metadata: 
status:
  refSource:
    uri: git+https://github.com/tektoncd/catalog.git
    digest:
      sha1: aeb957601cf41c012be462827053a21a420befca
    entrypoint: task/git-clone/0.6/git-clone.yaml
  data: a2luZDogVGFza...

uri

Git repository URL in SPDX download format

digest

Commit SHA (SHA-1 or SHA-256) of resolved revision

entrypoint

Path to the resource file in the repository
The Git Resolver supports both SHA-1 and SHA-256 commit hashes for revision validation. See the Git hash function transition for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us