Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 5. Authenticating pipelines with repositories using secrets

Pipelines and tasks can require credentials to authenticate with Git repositories and container repositories. In Red Hat OpenShift Pipelines, you can use secrets to authenticate pipeline runs and task runs that interact with a Git repository or container repository during execution.

A secret for authentication with a Git repository is known as a Git secret.

A pipeline run or a task run gains access to the secrets through an associated service account. Alternatively, you can define a workspace in the pipeline or task and bind the secret to the workspace.

5.1. Prerequisites
Copy link

  • You installed the oc OpenShift command line utility.

5.2. Providing secrets using service accounts
Copy link

You can use service accounts to provide secrets for authentication with Git repositories and container repositories.

You can associate a secret with a service account. The information in the secret becomes available to the tasks that run under this service account.

If you provide authentication secrets using service accounts, OpenShift Pipelines supports several secret types. For most of these secret types, you must provide annotations that define the repositories for which the authentication secret is valid.

5.2.1.1. Git authentication secrets
Copy link

If you provide authentication secrets using service accounts, OpenShift Pipelines supports the following types of secrets for Git authentication:

  • kubernetes.io/basic-auth: A username and password for basic authentication
  • kubernetes.io/ssh-auth: Keys for SSH-based authentication

If you provide authentication secrets using service accounts, a Git secret must have one or more annotation keys. The names of each key must begin with tekton.dev/git- and the value is the URL of the host for which OpenShift Pipelines must use the credentials in the secret.

In the following example, OpenShift Pipelines uses a basic-auth secret to access repositories at github.com and gitlab.com.

Example: Credentials for basic authentication with multiple Git repositories

apiVersion: v1
kind: Secret
metadata:
  name: git-secret-basic
  annotations:
    tekton.dev/git-0: github.com
    tekton.dev/git-1: gitlab.com
type: kubernetes.io/basic-auth
stringData:
  username: <username>
1 

  password: <password>
2
Copy to Clipboard Toggle word wrap

1
Username for the repository
2
Password or personal access token for the repository

You can also use ssh-auth secret to provide a private key for accessing a Git repository, as in the following example:

Example: Private key for SSH-based authentication

apiVersion: v1
kind: Secret
metadata:
  name: git-secret-ssh
  annotations:
    tekton.dev/git-0: https://github.com
type: kubernetes.io/ssh-auth
stringData:
  ssh-privatekey:
1
Copy to Clipboard Toggle word wrap

1
The content of the SSH private key file.

5.2.1.2. Container registry authentication secrets
Copy link

If you provide authentication secrets using service accounts, OpenShift Pipelines supports the following types of secrets for container (Docker) registry authentication:

  • kubernetes.io/basic-auth: A username and password for basic authentication
  • kubernetes.io/dockercfg: A serialized ~/.dockercfg file
  • kubernetes.io/dockerconfigjson: A serialized ~/.docker/config.json file

If you provide authentication secrets using service accounts, a container registry secret of the kubernetes.io/basic-auth type must have one or more annotation keys. The names of each key must begin with tekton.dev/docker- and the value is the URL of the host for which OpenShift Pipelines must use the credentials in the secret. This annotation is not required for other types of container registry secrets.

In the following example, OpenShift Pipelines uses a basic-auth secret, which relies on a username and password, to access container registries at quay.io and my-registry.example.com.

Example: Credentials for basic authentication with multiple container repositories

apiVersion: v1
kind: Secret
metadata:
  name: docker-secret-basic
  annotations:
    tekton.dev/docker-0: quay.io
    tekton.dev/docker-1: my-registry.example.com
type: kubernetes.io/basic-auth
stringData:
  username: <username>
1 

  password: <password>
2
Copy to Clipboard Toggle word wrap

1
Username for the registry
2
Password or personal access token for the registry

You can create kubernetes.io/dockercfg and kubernetes.io/dockerconfigjson secrets from an existing configuration file, as in the following example:

Example: Command for creating a secret for authenticating to a container repository from an existing configuration file

$ oc create secret generic docker-secret-config \
    --from-file=config.json=/home/user/.docker/config.json \
    --type=kubernetes.io/dockerconfigjson
Copy to Clipboard Toggle word wrap

You can also use the oc command line utility to create kubernetes.io/dockerconfigjson secrets from credentials, as in the following example:

Example: Command for creating a secret for authenticating to a container repository from credentials

$ oc create secret docker-registry docker-secret-config \
  --docker-email=<email> \
1 

  --docker-username=<username> \
2 

  --docker-password=<password> \
3 

  --docker-server=my-registry.example.com:5000
4
Copy to Clipboard Toggle word wrap

1
Email address for the registry
2
Username for the registry
3
Password or personal access token for the registry
4
The host name and port for the registry

For a pipeline to retrieve resources from password-protected repositories, you can configure the basic authentication for that pipeline.

Note

Consider using SSH-based authentication rather than basic authentication.

To configure basic authentication for a pipeline, create a basic authentication secret, associate this secret with a service account, and associate this service account with a TaskRun or PipelineRun resource.

Note

For GitHub, authentication using a plain password is deprecated. Instead, use a personal access token.

Procedure

  1. Create the YAML manifest for the secret in the secret.yaml file. In this manifest, specify the username and password or GitHub personal access token to access the target Git repository. 

    apiVersion: v1
kind: Secret
metadata:
  name: basic-user-pass
    1 
    
  annotations:
    tekton.dev/git-0: https://github.com
type: kubernetes.io/basic-auth
stringData:
  username: <username>
    2 
    
  password: <password>
    3
    Copy to Clipboard Toggle word wrap
    1
    Name of the secret. In this example, basic-user-pass.
    2
    Username for the Git repository.
    3
    Password or personal access token for the Git repository.

  2. Create the YAML manifest for the service account in the serviceaccount.yaml file. In this manifest, associate the secret with the service account. 

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-bot
    1 
    
secrets:
  - name: basic-user-pass
    2
    Copy to Clipboard Toggle word wrap
    1
    Name of the service account. In this example, build-bot.
    2
    Name of the secret. In this example, basic-user-pass.

  3. Create the YAML manifest for the task run or pipeline run in the run.yaml file and associate the service account with the task run or pipeline run. Use one of the following examples:

    • Associate the service account with a TaskRun resource: 

      apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: build-push-task-run-2
      1 
      
spec:
  taskRunTemplate:
    serviceAccountName: build-bot
      2 
      
  taskRef:
    name: build-push
      3
      Copy to Clipboard Toggle word wrap
      1
      Name of the task run. In this example, build-push-task-run-2.
      2
      Name of the service account. In this example, build-bot.
      3
      Name of the task. In this example, build-push.

    • Associate the service account with a PipelineRun resource: 

      apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: demo-pipeline
      1 
      
  namespace: default
spec:
  taskRunTemplate:
    serviceAccountName: build-bot
      2 
      
  pipelineRef:
    name: demo-pipeline
      3
      Copy to Clipboard Toggle word wrap
      1
      Name of the pipeline run. In this example, demo-pipeline.
      2
      Name of the service account. In this example, build-bot.
      3
      Name of the pipeline. In this example, demo-pipeline.

  4. Apply the YAML manifests that you created by entering the following command: 

    $ oc apply --filename secret.yaml,serviceaccount.yaml,run.yaml
    Copy to Clipboard Toggle word wrap

For a pipeline to retrieve resources from repositories configured with SSH keys, you must configure the SSH-based authentication for that pipeline.

To configure SSH-based authentication for a pipeline, create an authentication secret with the SSH private key, associate this secret with a service account, and associate this service account with a TaskRun or PipelineRun resource.

Procedure

  1. Generate an SSH private key, or copy an existing private key, which is usually available in the ~/.ssh/id_rsa file.

  2. Create the YAML manifest for the secret in the secret.yaml file. In this manifest, set the value of ssh-privatekey to the content of the SSH private key file, and set the value of known_hosts to the content of the known hosts file. 

    apiVersion: v1
kind: Secret
metadata:
  name: ssh-key
    1 
    
  annotations:
    tekton.dev/git-0: github.com
type: kubernetes.io/ssh-auth
stringData:
  ssh-privatekey:
    2 
    
  known_hosts:
    3
    Copy to Clipboard Toggle word wrap
    1
    Name of the secret containing the SSH private key. In this example, ssh-key.
    2
    The content of the SSH private key file.
    3
    The content of the known hosts file.
    Important

    If you omit the known hosts file, OpenShift Pipelines accepts the public key of any server.

  3. Optional: Specify a custom SSH port by adding :<port_number> to the end of the annotation value. For example, tekton.dev/git-0: github.com:2222.

  4. Create the YAML manifest for the service account in the serviceaccount.yaml file. In this manifest, associate the secret with the service account. 

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-bot
    1 
    
secrets:
  - name: ssh-key
    2
    Copy to Clipboard Toggle word wrap
    1
    Name of the service account. In this example, build-bot.
    2
    Name of the secret containing the SSH private key. In this example, ssh-key.

  5. In the run.yaml file, associate the service account with a task run or a pipeline run. Use one of the following examples:

    • To associate the service account with a task run: 

      apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: build-push-task-run-2
      1 
      
spec:
  taskRunTemplate:
    serviceAccountName: build-bot
      2 
      
  taskRef:
    name: build-push
      3
      Copy to Clipboard Toggle word wrap
      1
      Name of the task run. In this example, build-push-task-run-2.
      2
      Name of the service account. In this example, build-bot.
      3
      Name of the task. In this example, build-push.

    • To associate the service account with a pipeline run: 

      apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: demo-pipeline
      1 
      
  namespace: default
spec:
  taskRunTemplate:
    serviceAccountName: build-bot
      2 
      
  pipelineRef:
    name: demo-pipeline
      3
      Copy to Clipboard Toggle word wrap
      1
      Name of the pipeline run. In this example, demo-pipeline.
      2
      Name of the service account. In this example, build-bot.
      3
      Name of the pipeline. In this example, demo-pipeline.

  6. Apply the changes. 

    $ oc apply --filename secret.yaml,serviceaccount.yaml,run.yaml
    Copy to Clipboard Toggle word wrap

For a pipeline to retrieve container images from a registry or push container images to a registry, you must configure the authentication for that registry.

To configure registry authentication for a pipeline, create an authentication secret with the Docker configuration file, associate this secret with a service account, and associate this service account with a TaskRun or PipelineRun resource.

Procedure

  1. Create the container registry authentication secret from an existing config.json file, which contains the authentication information, by entering the following command: 

    $ oc create secret generic my-registry-credentials \
    1 
    
  --from-file=config.json=/home/user/credentials/config.json
    2
    Copy to Clipboard Toggle word wrap
    1
    The name of the secret, in this example, my-registry-credentials
    2
    The path name of the config.json file, in this example, /home/user/credentials/config.json

  2. Create the YAML manifest for the service account in the serviceaccount.yaml file. In this manifest, associate the secret with the service account. 

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: container-bot
    1 
    
secrets:
  - name: my-registry-credentials
    2
    Copy to Clipboard Toggle word wrap
    1
    Name of the service account. In this example, container-bot.
    2
    Name of the secret containing the SSH private key. In this example, my-registry-credentials.

  3. Create a YAML manifest for a task run or pipeline run as the run.yaml file. In this file, associate the service account with a task run or a pipeline run. Use one of the following examples:

    • To associate the service account with a task run: 

      apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: build-container-task-run-2
      1 
      
spec:
  taskRunTemplate:
    serviceAccountName: container-bot
      2 
      
  taskRef:
    name: build-container
      3
      Copy to Clipboard Toggle word wrap
      1
      Name of the task run. In this example, build-container-task-run-2.
      2
      Name of the service account. In this example, container-bot.
      3
      Name of the task. In this example, build-container.

    • To associate the service account with a pipeline run: 

      apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: demo-pipeline
      1 
      
  namespace: default
spec:
  taskRunTemplate:
    serviceAccountName: container-bot
      2 
      
  pipelineRef:
    name: demo-pipeline
      3
      Copy to Clipboard Toggle word wrap
      1
      Name of the pipeline run. In this example, demo-pipeline.
      2
      Name of the service account. In this example, container-bot.
      3
      Name of the pipeline. In this example, demo-pipeline.

  4. Apply the changes by entering the following command: 

    $ oc apply --filename serviceaccount.yaml,run.yaml
    Copy to Clipboard Toggle word wrap

In certain cases, you must complete additional steps to use authentication secrets that you provide using service accounts.

5.2.5.1. SSH Git authentication in tasks
Copy link

You can directly invoke Git commands in the steps of a task and use SSH authentication, but you must complete an additional step.

OpenShift Pipelines provides the SSH files in the /tekton/home/.ssh directory and sets the $HOME variable to /tekton/home. However, Git SSH authentication ignores the $HOME variable and uses the home directory specified in the /etc/passwd file for the user. Therefore, a step that uses Git command must symlink the /tekton/home/.ssh directory to the home directory of the associated user.

For example, if the task runs as the root user, the step must include the following command before Git commands: 

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: example-git-task
spec:
  steps:
    - name: example-git-step
#     ...
      script:
        ln -s $HOME/.ssh /root/.ssh
#     ...
Copy to Clipboard Toggle word wrap

However, explicit symlinks are not necessary when you use a pipeline resource of the git type or the git-clone task available in the Tekton catalog.

As an example of using SSH authentication in git type tasks, refer to authenticating-git-commands.yaml.

5.2.5.2. Use of secrets as a non-root user
Copy link

You might need to use secrets as a non-root user in certain scenarios, such as:

  • The users and groups that the containers use to execute runs are randomized by the platform.
  • The steps in a task define a non-root security context.
  • A task specifies a global non-root security context, which applies to all steps in a task.

In such scenarios, consider the following aspects of executing task runs and pipeline runs as a non-root user:

  • SSH authentication for Git requires the user to have a valid home directory configured in the /etc/passwd directory. Specifying a UID that has no valid home directory results in authentication failure.
  • SSH authentication ignores the $HOME environment variable. So you must or symlink the appropriate secret files from the $HOME directory defined by OpenShift Pipelines (/tekton/home), to the non-root user’s valid home directory.

In addition, to configure SSH authentication in a non-root security context, refer to the git-clone-and-check step in the example for authenticating git commands.

5.3. Providing secrets using workspaces
Copy link

You can use workspaces to provide secrets for authentication with Git repositories and container repositories.

You can configure a named workspace in a task, specifying a path where the workspace is mounted. When you run the task, provide the secret as the workspace with this name. When OpenShift Pipelines executes the task, the information in the secret is available to the task.

If you provide authentication secrets using workspaces, annotations for the secrets are not required.

For a pipeline to retrieve resources from repositories configured with SSH keys, you must configure the SSH-based authentication for that pipeline.

To configure SSH-based authentication for a pipeline, create an authentication secret with the SSH private key, configure a named workspace for this secret in the task, and specify the secret when running the task.

Procedure

  1. Create the Git SSH authentication secret from files in an existing .ssh directory by entering the following command: 

    $ oc create secret generic my-github-ssh-credentials \
    1 
    
  --from-file=id_ed25519=/home/user/.ssh/id_ed25519 \
    2 
    
  --from-file=known_hosts=/home/user/.ssh/known_hosts
    3
    Copy to Clipboard Toggle word wrap
    1
    The name of the secret, in this example, my-github-ssh-credentials
    2
    The name and full path name of the private key file, in this example, /home/user/.ssh/id_ed25519
    3
    The name and full path name of the known hosts file, in this example, /home/user/.ssh/known_hosts

  2. In your task definition, configure a named workspace for the Git authentication, for example, ssh-directory:

    Example definition of a workspace

    apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: git-clone
spec:
  workspaces:
    - name: ssh-directory
      description: |
        A .ssh directory with private key, known_hosts, config, etc.
    Copy to Clipboard Toggle word wrap

  3. In the steps of the task, access the directory using the path in the $(workspaces.<workspace_name>.path) environment variable, for example, $(workspaces.ssh-directory.path)

  4. When running the task, specify the secret for the named workspace by including the --workspace argument in the tkn task start command: 

    $ tkn task start <task_name>
      --workspace name=<workspace_name>,secret=<secret_name>
    1 
    
      # ...
    Copy to Clipboard Toggle word wrap
    1
    Replace <workspace_name> with the name of the workspace that you configured and <secret_name> with the name of the secret that you created.

Example task for cloning a Git repository using an SSH key for authentication

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: git-clone
spec:
  workspaces:
    - name: output
      description: The git repo will be cloned onto the volume backing this Workspace.
    - name: ssh-directory
      description: |
        A .ssh directory with private key, known_hosts, config, etc. Copied to
        the user's home before git commands are executed. Used to authenticate
        with the git remote when performing the clone. Binding a Secret to this
        Workspace is strongly recommended over other volume types
  params:
    - name: url
      description: Repository URL to clone from.
      type: string
    - name: revision
      description: Revision to checkout. (branch, tag, sha, ref, etc...)
      type: string
      default: ""
    - name: gitInitImage
      description: The image providing the git-init binary that this Task runs.
      type: string
      default: "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/git-init:v0.37.0"
  results:
    - name: commit
      description: The precise commit SHA that was fetched by this Task.
    - name: url
      description: The precise URL that was fetched by this Task.
  steps:
    - name: clone
      image: "$(params.gitInitImage)"
      script: |
        #!/usr/bin/env sh
        set -eu
        # This is necessary for recent version of git
        git config --global --add safe.directory '*'
        cp -R "$(workspaces.ssh-directory.path)" "${HOME}"/.ssh
1 

        chmod 700 "${HOME}"/.ssh
        chmod -R 400 "${HOME}"/.ssh/*
        CHECKOUT_DIR="$(workspaces.output.path)/"
        /ko-app/git-init \
          -url="$(params.url)" \
          -revision="$(params.revision)" \
          -path="${CHECKOUT_DIR}"
        cd "${CHECKOUT_DIR}"
        RESULT_SHA="$(git rev-parse HEAD)"
        EXIT_CODE="$?"
        if [ "${EXIT_CODE}" != 0 ] ; then
          exit "${EXIT_CODE}"
        fi
        printf "%s" "${RESULT_SHA}" > "$(results.commit.path)"
        printf "%s" "$(params.url)" > "$(results.url.path)"
Copy to Clipboard Toggle word wrap

1
The script copies the content of the secret (in the form of a folder) to ${HOME}/.ssh, which is the standard folder where ssh searches for credentials.

Example command for running the task

$ tkn task start git-clone
      --param url=git@github.com:example-github-user/buildkit-tekton
      --workspace name=output,emptyDir=""
      --workspace name=ssh-directory,secret=my-github-ssh-credentials
      --use-param-defaults --showlog
Copy to Clipboard Toggle word wrap

For a pipeline to retrieve container images from a registry, you must configure the authentication for that registry.

To configure authentication for a container registry, create an authentication secret with the Docker configuration file, configure a named workspace for this secret in the task, and specify the secret when running the task.

Procedure

  1. Create the container registry authentication secret from an existing config.json file, which contains the authentication information, by entering the following command: 

    $ oc create secret generic my-registry-credentials \
    1 
    
  --from-file=config.json=/home/user/credentials/config.json
    2
    Copy to Clipboard Toggle word wrap
    1
    The name of the secret, in this example, my-registry-credentials
    2
    The path name of the config.json file, in this example, /home/user/credentials/config.json

  2. In your task definition, configure a named workspace for the Git authentication, for example, ssh-directory:

    Example definition of a workspace

    apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: skopeo-copy
spec:
  workspaces:
    - name: dockerconfig
      description: Includes a docker `config.json`
# ...
    Copy to Clipboard Toggle word wrap

  3. In the steps of the task, access the directory by using the path in the $(workspaces.<workspace_name>.path) environment variable, for example, $(workspaces.dockerconfig.path).

  4. To run the task, specify the secret for the named workspace by including the --workspace argument in the tkn task start command: 

    $ tkn task start <task_name>
      --workspace name=<workspace_name>,secret=<secret_name>
    1 
    
      # ...
    Copy to Clipboard Toggle word wrap
    1
    Replace <workspace_name> with the name of the workspace that you configured and <secret_name> with the name of the secret that you created.

Example task for copying an image from a container repository using Skopeo

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: skopeo-copy
spec:
  workspaces:
    - name: dockerconfig
1 

      description: Includes a docker `config.json`
  steps:
    - name: clone
      image: quay.io/skopeo/stable:v1.8.0
      env:
      - name: DOCKER_CONFIG
        value: $(workspaces.dockerconfig.path)
2 

      script: |
        #!/usr/bin/env sh
        set -eu
        skopeo copy docker://docker.io/library/ubuntu:latest docker://quay.io/example_repository/ubuntu-copy:latest
Copy to Clipboard Toggle word wrap

1
The name of the workspace that contains the config.json file.
2
The DOCKER_CONFIG environment variable points to the location of the config.json file in the dockerconfig workspace. Skopeo uses this environment variable to get the authentication information.

Example command for running the task

$ tkn task start skopeo-copy
      --workspace name=dockerconfig,secret=my-registry-credentials
      --use-param-defaults --showlog
Copy to Clipboard Toggle word wrap

When you provide authentication secrets using workspaces and define the workspace in a task, by default the workspace is available to all steps in the task.

To limit a secret to specific steps, define the workspace both in the task specification and in the step specification.

Procedure

  • Add the workspaces: definition under both the task specification and the step specification, as in the following example:

    Example task definition where only one step can access the credentials workspace

    apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: git-clone-build
spec:
  workspaces:
    1 
    
    - name: ssh-directory
      description: |
        A .ssh directory with private key, known_hosts, config, etc.
# ...
  steps:
    - name: clone
      workspaces:
    2 
    
        - name: ssh-directory
# ...
    - name: build
    3 
    
# ...
    Copy to Clipboard Toggle word wrap

    1
    The definition of the ssh-directory workspace in the task specification.
    2
    The definition of the ssh-directory workspace in the step specification. The authentication information is available to this step as the $(workspaces.ssh-directory.path) directory.
    3
    As this step does not include a definition of the ssh-directory workspace, the authentication information is not available to this step.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat