Skip to main content
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:[email protected]

​
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": "[email protected]"
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us