Prepare Git Credential

This guide shows you how to create a git credential Secret that help you run your Tekton Tasks and Pipelines.

This document will use the configuration of a git-clone Task as an example. If you are using a different Task, you can refer to the steps here and modify the taskRef.name and workspaces to match those defined in your Task.

Prerequisites

kubectl installed and configured to access the cluster.
Permissions to read and write Secrets.

Steps

Optional 1: Using ssh Credentials

This Task supports fetching private repositories. There are three ways to authenticate:

The simplest approach is to bind an ssh-directory workspace to this Task. The workspace should contain private keys (e.g. id_rsa), config and known_hosts files - anything you need to interact with your git remote via SSH. It's strongly recommended that you use Kubernetes Secrets to hold your credentials and bind to this workspace.

In a TaskRun that would look something like this:

kind: TaskRun
spec:
  workspaces:
  - name: ssh-directory
    secret:
      secretName: my-ssh-credentials

And in a Pipeline and PipelineRun it would look like this:

kind: Pipeline
spec:
  workspaces:
  - name: ssh-creds
  # ...
  tasks:
  - name: fetch-source
    taskRef:
      name: git-clone
    workspaces:
    - name: ssh-directory
      workspace: ssh-creds
  # ...
---
kind: PipelineRun
spec:
  workspaces:
  - name: ssh-creds
    secret:
      secretName: my-ssh-credentials
  # ...

The Secret would appear the same in both cases - structured like a .ssh directory:

kind: Secret
apiVersion: v1
metadata:
  name: my-ssh-credentials
data:
  id_rsa: # ... base64-encoded private key ...
  known_hosts: # ... base64-encoded known_hosts file ...
  config: # ... base64-encoded ssh config file ...

Including known_hosts is optional but strongly recommended. Without it the git-clone Task will blindly accept the remote server's identity.

Another approach is to bind an ssl-ca-directory workspace to this Task. The workspace should contain crt keys (e.g. ca-bundle.crt)files - anything you need to interact with your git remote via custom CA . It's strongly recommended that you use Kubernetes Secrets to hold your credentials and bind to this workspace.

In a TaskRun that would look something like this:

kind: TaskRun
spec:
  workspaces:
  - name: ssl-ca-directory
    secret:
      secretName: my-ssl-credentials

And in a Pipeline and PipelineRun it would look like this:

kind: Pipeline
spec:
  workspaces:
  - name: ssl-creds
  # ...
  tasks:
  - name: fetch-source
    taskRef:
      name: git-clone
    workspaces:
    - name: ssl-ca-directory
      workspace: ssl-creds
  # ...
---
kind: PipelineRun
spec:
  workspaces:
  - name: ssl-creds
    secret:
      secretName: my-ssl-credentials
  # ...

The Secret would appear like below:

kind: Secret
apiVersion: v1
metadata:
  name: my-ssl-credentials
data:
  ca-bundle.crt: # ... base64-encoded crt ...  # If key/filename is other than ca-bundle.crt then set crtFileName param as explained under Parameters section

Optional 2: Using basic-auth Credentials

Note: It is strongly advised that you use ssh credentials when the option is available to you before using basic auth. You can generate a short lived token from WebVCS platforms (Github, Gitlab, Bitbucket etc..) to be used as a password and generally be able to use git as the username. On bitbucket server the token may have a / into it so you would need to urlquote them before in the Secret, see this stackoverflow answer :

https://stackoverflow.com/a/24719496

To support basic-auth this Task exposes an optional basic-auth Workspace. The bound Workspace should contain a .gitconfig or .git-credentials file. Any other files on this Workspace are ignored. A typical Secret containing these credentials looks as follows:

kind: Secret
apiVersion: v1
metadata:
  name: my-basic-auth-secret
type: Opaque
stringData:
  .gitconfig: |
    [credential "https://<hostname>"]
      helper = store
  .git-credentials: |
    https://<user>:<pass>@<hostname>

Optional 3: Using Git Connector

The task can be used with Git Connector to enhance security.

You need to create the Git Connector first, then in the TaskRun, use CSI to configure the basic-auth workspace.

Git Connector currently only supports cloning with basic-auth, not with ssh.

Here is an example of how to use Git Connector in git-clone TaskRun:

Create Git Connector

cat <<EOF | kubectl apply -f -
kind: Secret
apiVersion: v1
metadata:
  name: github
type: kubernetes.io/basic-auth
stringData:
  username: your-username # Replace with your Git username
  password: your-token    # Replace with your Git password or token
---
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: github
spec:
  connectorClassName: git
  address: https://github.com  # Replace with your Git server address
  auth:
    name: basicAuth
    secretRef:
      name: github
    params:
    - name: repository
      value: your-org/your-repo.git  # Replace with your repository path which could access by your token, this is used for health check
EOF

Create TaskRun

cat << EOF | kubectl apply -f -
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: git-clone-demo
spec:
  params:
  - name: url
    value: https://github.com/your-org/your-repo.git # Replace with your repository path which you want to clone
  - name: revision
    value: refs/heads/main
  taskRef:
    name: git-clone
  timeout: 10m0s
  computeResources:
    limits:
      cpu: 200m
      memory: 200Mi
    requests:
      cpu: 200m
      memory: 200Mi
  workspaces:
  - name: output
    emptyDir: {}
  - csi:
      driver: connectors-csi
      readOnly: true
      volumeAttributes:
        connector.name: github #  the name of the connector
        connector.namespace: "" # the namespace of the connector, if not specified, the same namespace as the TaskRun will be used
        configuration.names: "gitconfig" # the name of the configuration, which is fixed as "gitconfig"
    name: basic-auth
EOF

More about Connector, please refer to Alauda DevOps Connectors Doc.

#Prepare Git Credential

#TOC

#Prerequisites

#Steps

#Optional 1: Using ssh Credentials

#Optional 2: Using basic-auth Credentials