Skip to content

Latest commit

 

History

History
146 lines (105 loc) · 8.9 KB

task-git-clone.md

File metadata and controls

146 lines (105 loc) · 8.9 KB
Raw

git-clone Tekton Task

The git-clone Task will clone and prepare a Git repository on the output Workspace. By default the Git repository (URL) will be cloned on the root of the Workspace, but you can alter the clone location using the SUBDIRECTORY parameter, and other settings.

A quick usage example is:

---
apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: example-taskrun
spec:
  taskRef:
    name: git-clone
  params:
    - name: URL
      value: https://github.com/openshift-pipelines/task-git.git
  workspaces:
    - name: output
      emptyDir: {}

Please consider the Workspaces, Parameters and Results described below.

Workspaces

A single Workspace is required for this Task, while the optional Workspaces will allow advanced Git configuration and authentication.

output

The output is a required Workspace, represents the primary location where the Git repository data will be stored, and later on, this Workspace will be mounted in subsequent Pipeline's Task.

Knowing the Workspace data will be employed on other Tasks, the recommended approach is using a persistent volume, for instance a PersistentVolumeClaim (PVC).

Authentication Workspaces

The recommended approach to authentication is using the default mechanisms supported by Tekton Pipeline, please consider it as your first option.

More advanced use-cases may require different methods of interacting with private repositories, the following Workspaces are meant to support advanced Git configuration and authentication.

basic-auth (HTTP/SSH)

The basic-auth is a optional Workspace to provide Git credentials and configuration.

The following Workspace files (items) are shared with Git before cloning the repository, the Task copies the files to the Git user home directory, configured by the parameter USER_HOME.

Workspace File Required Description
.git-credentials true Git credentials file
.gitconfig true Git configuration file

Typically, this type of data is stored as a Kubernetes Secret. For example:

kubectl create secret generic basic-auth-ex \
	--from-file=".git-credentials=${HOME}/.git-credentials" \
	--from-file=".gitconfig=${HOME}/.gitconfig"

Then, you can reference the Secret as the basic-auth Workspace.

ssh-directory (SSH)

The ssh-directory is a optional Workspace, meant to store the files commonly found on a ~/.ssh directory, when informed, the whole directory will be copied into the Git's home (configured by the parameter USER_HOME).

During the prepare step you can see the details about what's being copied, please consider the output log snippet below. For more verbose logging set the peramater VERBOSE to true.

---> Phase: Copying '.ssh' from ssh-directory workspace ('/workspaces/ssh-directory')...
'/workspaces/ssh-directory' -> '/home/git/.ssh'
'/workspaces/ssh-directory/config' -> '/home/git/.ssh/config'
mode of '/home/git/.ssh' changed from 0755 (rwxr-xr-x) to 0700 (rwx------)
mode of '/home/git/.ssh/config' changed from 0644 (rw-r--r--) to 0400 (r--------)

It's recommended storing this type of data as a Kubernetes Secret, like the following example:

kubectl create secret generic ssh-directory-ex \
	--from-file="config=${HOME}/.ssh/config" \
	--from-file="authorized_keys=${HOME}/.ssh/authorized_keys"

Then, you can reference the Secret as the ssh-directory Workspace.

ssl-ca-directory (mTLS)

The ssl-ca-directory is a optional Workspace to store a additional Certificate Authority (CA) bundles, commonly .pem or .crt files. The exact bundle file name is defined by the parameter CRT_FILENAME.

Before running the Git clone command, the GIT_SSL_CAINFO environment variable is exported with the full path to the CRT_FILENAME in the ssl-ca-directory Workspace.

You can observe the setting taking place on the beggining of the git-clone step:

phase 'Exporting custom CA certificate "GIT_SSL_CAINFO=/workspaces/ssl-ca-directory/ca-bundle.crt"'

This is a sensitive information and therefore it's recommended to store as a Kubernetes Secret, please consider the previous examples to create Secrets with the --from-file option.

Finally, you can reference the Secret as the ssl-ca-directory Workspace.

Parameters

The following parameters are supported by this Task.

Parameter Type Default Description
URL string (required) Git repository URL
REVISION string main Revision to checkout, an branch, tag, sha, ref, etc...
SUBMODULES string true Initialize and fetch Git submodules
DEPTH string 1 Number of commits to fetch, a "shallow clone" is a single commit
SSL_VERIFY string true Sets the global http.sslVerify value, false is not advised unless you trust the remote repository
CRT_FILENAME string ca-bundle.crt Certificate Authority (CA) bundle filename on the ssl-ca-directory Workspace.
SUBDIRECTORY string "" (empty) Relative path to the output Workspace where the repository will be cloned
SPARSE_CHECKOUT_DIRECTORIES string "" (empty) List of directory patterns split by comma to perform "sparse checkout"
DELETE_EXISTING string true Clean out the contents of the output Workspace before cloning the repository, if data exists.
HTTP_PROXY string "" (empty) HTTP proxy server (non-TLS requests)
HTTPS_PROXY string "" (empty) HTTPS proxy server (TLS requests)
NO_PROXY string "" (empty) Opt out of proxying HTTP/HTTPS requests
VERBOSE string false Log the commands executed
USER_HOME string /home/git Absolute path to the Git user home directory

Results

The following results are produced by this Task.

Name Description
COMMIT The precise commit SHA digest cloned
URL The precise repository URL
COMMITTER_DATE The epoch timestamp of the commit cloned