Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tektoncd/pipeline/llms.txt

Use this file to discover all available pages before exploring further.

Tekton supports authentication for Git repositories and Docker registries using Kubernetes Secrets. This guide shows you how to configure authentication for your TaskRuns and PipelineRuns.

​
Overview

Tekton supports authentication via Kubernetes first-class Secret types:
  • Git: kubernetes.io/basic-auth and kubernetes.io/ssh-auth
  • Docker: kubernetes.io/basic-auth, kubernetes.io/dockercfg, and kubernetes.io/dockerconfigjson
A TaskRun or PipelineRun gains access to these Secrets through its associated ServiceAccount. Tekton converts properly annotated Secrets and stores them in a Step’s container as:
  • Git: ~/.gitconfig file or ~/.ssh directory
  • Docker: ~/.docker/config.json file
Tekton performs credential initialization within every Pod before executing any Steps, accessing each Secret and aggregating them into /tekton/creds before copying or symlinking files to the user’s $HOME directory.

​
Understanding Credential Selection

You must annotate each Secret to specify the domains for which Tekton can use the credentials. Tekton ignores all Secrets that are not properly annotated. A credential annotation key must begin with tekton.dev/git- or tekton.dev/docker- and its value is the URL of the host: 
apiVersion: v1
kind: Secret
metadata:
  annotations:
    tekton.dev/git-0: https://github.com
    tekton.dev/git-1: https://gitlab.com
    tekton.dev/docker-0: https://gcr.io
type: kubernetes.io/basic-auth
stringData:
  username: <cleartext username>
  password: <cleartext password>
For SSH authentication with Git: 
apiVersion: v1
kind: Secret
metadata:
  annotations:
    tekton.dev/git-0: github.com
type: kubernetes.io/ssh-auth
stringData:
  ssh-privatekey: <private-key>
  known_hosts: <known-hosts>
Always include a known_hosts entry in SSH Secrets as a security measure. Omitting this results in the server’s public key being blindly accepted.

​
Configuring Git Authentication

​
Basic Authentication for Git

1

Create the Secret

Define a Secret with your username and password (or personal access token for GitHub):
apiVersion: v1
kind: Secret
metadata:
  name: basic-user-pass
  annotations:
    tekton.dev/git-0: https://github.com
type: kubernetes.io/basic-auth
stringData:
  username: <cleartext username>
  password: <cleartext password>
GitHub deprecated basic authentication with username and password. Use a personal access token instead of a cleartext password. See GitHub’s documentation.
2

Create a ServiceAccount

Associate the Secret with a ServiceAccount:
apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-bot
secrets:
  - name: basic-user-pass
3

Reference the ServiceAccount

Associate the ServiceAccount with your TaskRun or PipelineRun:
apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: build-push-task-run-2
spec:
  serviceAccountName: build-bot
  taskRef:
    name: build-push
4

Apply the configuration

kubectl apply --filename secret.yaml serviceaccount.yaml run.yaml

​
SSH Authentication for Git

1

Create the SSH Secret

Define a Secret with your SSH private key:
apiVersion: v1
kind: Secret
metadata:
  name: ssh-key
  annotations:
    tekton.dev/git-0: github.com
type: kubernetes.io/ssh-auth
stringData:
  ssh-privatekey: <private-key>
  known_hosts: <known-hosts>
2

Generate the private key

cat ~/.ssh/id_rsa
Set the value of the known_hosts field to the appropriate value for your Git server.
3

Create a ServiceAccount

apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-bot
secrets:
  - name: ssh-key
4

Apply and use

kubectl apply --filename secret.yaml,serviceaccount.yaml,run.yaml

​
Custom SSH Port

You can specify a custom SSH port in your Secret annotation: 
apiVersion: v1
kind: Secret
metadata:
  name: ssh-key-custom-port
  annotations:
    tekton.dev/git-0: example.com:2222
type: kubernetes.io/ssh-auth
stringData:
  ssh-privatekey: <private-key>
  known_hosts: <known-hosts>

​
Configuring Docker Authentication

​
Basic Authentication for Docker

1

Create the Secret

apiVersion: v1
kind: Secret
metadata:
  name: basic-user-pass
  annotations:
    tekton.dev/docker-0: https://gcr.io
type: kubernetes.io/basic-auth
stringData:
  username: <cleartext username>
  password: <cleartext password>
2

Create a ServiceAccount

apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-bot
secrets:
  - name: basic-user-pass
3

Reference in TaskRun or PipelineRun

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: demo-pipeline
  namespace: default
spec:
  serviceAccountName: build-bot
  pipelineRef:
    name: demo-pipeline

​
Docker Config Authentication

Use your existing Docker client configuration:
1

Create Secret from Docker config

kubectl create secret generic regcred \
  --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
  --type=kubernetes.io/dockerconfigjson
2

Associate with ServiceAccount

apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-bot
secrets:
  - name: regcred
If you specify both Tekton basic-auth and Kubernetes dockerconfigjson Secrets, Tekton merges all credentials but basic-auth overrides the Kubernetes Secrets.

​
Using Secrets as a Non-Root User

When running Steps as a non-root user, consider the following:
  • SSH authentication for Git requires the user to have a valid home directory in /etc/passwd
  • SSH ignores the $HOME environment variable, so you must symlink or move Secret files from /tekton/home to the non-root user’s home directory
Example from the authenticating-git-commands sample: 
- name: git-clone-and-check
  image: alpine-git-nonroot:latest
  securityContext:
    runAsUser: 1000
  script: |
    #!/usr/bin/env ash
    # Symlink credentials to non-root user's home
    ln -s $(credentials.path)/.ssh /home/nonroot/.ssh
    git clone root@localhost:/root/repo ./repo

​
Limiting Secret Access to Specific Steps

By default, Tekton makes Secrets available to all Steps. To limit a Secret to specific Steps:
  1. Do not use the ServiceAccount-based approach described above
  2. Instead, explicitly specify a Volume using the Secret definition
  3. Manually mount it only into the desired Steps using VolumeMount

​
Disabling Built-In Authentication

To disable Tekton’s built-in credential handling, edit the feature-flag ConfigMap: 
kubectl edit configmap feature-flag -n tekton-pipelines
Set disable-creds-init to "true".
After disabling built-in auth, you must pass credentials explicitly to Tasks using Workspaces, environment variables, or custom volumes.

​
Troubleshooting

This warning can occur for several reasons:Multiple Steps with varying UIDsSteps with different users/UIDs trying to initialize credentials in the same Task. Solution: Ensure all Steps run with the same UID using a TaskRun’s Pod template field.Workspace or Volume also mountedA Task has both a Workspace/Volume for credentials and a ServiceAccount with credentials. Solution: Don’t mix credentials mounted via Workspace with those initialized via ServiceAccount.Read-only Workspace for $HOMEA Task has a read-only Workspace mounted for the HOME directory. Solution: Don’t mix credentials mounted via Workspace with ServiceAccount-based initialization.Step named image-digest-exporterIf this warning appears for the image-digest-exporter Step, you can safely ignore it. This Step is injected by Tekton and doesn’t use the credentials.

​
Technical Reference

​
Basic Auth for Git

Tekton generates the following files: 
=== ~/.gitconfig ===
[credential]
    helper = store
[credential "https://url1.com"]
    username = "user1"

=== ~/.git-credentials ===
https://user1:pass1@url1.com

​
SSH Auth for Git

Tekton generates: 
=== ~/.ssh/id_key1 ===
{contents of key1}

=== ~/.ssh/config ===
Host url1.com
    HostName url1.com
    IdentityFile ~/.ssh/id_key1

=== ~/.ssh/known_hosts ===
{contents of known_hosts1}

​
Basic Auth for Docker

Tekton generates: 
{
  "auths": {
    "https://url1.com": {
      "auth": "base64(user1:pass1)",
      "email": "not@val.id"
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us