Skip to content

Commit 54fde69

Browse files
QuanZhang-WilliamQuanZhang-William
committed
Migrate git-clone resources from Tekton Community Catalog
This is the initial commit to migrate git-clone resource from Tekton Community Catalog (https://github.com/tektoncd/catalog/tree/main/task/git-clone/0.8) to a standalone repo under the Tekton Official Catalog organization, following git-based versioning as documented in TEP-0115: https://github.com/tektoncd/community/blob/main/teps/0115-tekton-catalog-git-based-versioning.md
0 parents  commit 54fde69

8 files changed

+1155
-0
lines changed

‎task/git-clone/README.md

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
# `git-clone`
2+
3+
**Note: this Task is only compatible with Tekton Pipelines versions 0.29.0 and greater!**
4+
5+
**Note: this Task is not backwards compatible with the previous versions as it is now run as a non-root user!**
6+
7+
This `Task` has two required inputs:
8+
9+
1. The URL of a git repo to clone provided with the `url` param.
10+
2. A Workspace called `output`.
11+
12+
The `git-clone` `Task` will clone a repo from the provided `url` into the
13+
`output` Workspace. By default the repo will be cloned into the root of
14+
your Workspace. You can clone into a subdirectory by setting this `Task`'s
15+
`subdirectory` param. If the directory where the repo will be cloned is
16+
already populated then by default the contents will be deleted before the
17+
clone takes place. This behaviour can be disabled by setting the
18+
`deleteExisting` param to `"false"`.
19+
20+
**Note**: The `git-clone` Task is run as nonroot. The files cloned on to the `output`
21+
workspace will end up owned by user 65532.
22+
23+
## Workspaces
24+
25+
**Note**: This task is run as a non-root user with UID 65532 and GID 65532.
26+
Generally, the default permissions for storage volumes are configured for the
27+
root user. To make the volumes accessible by the non-root user, you will need
28+
to either configure the permissions manually or set the `fsGroup` field under
29+
`PodSecurityContext` in your TaskRun or PipelineRun.
30+
31+
An example PipelineRun will look like:
32+
```yaml
33+
apiVersion: tekton.dev/v1beta1
34+
kind: PipelineRun
35+
metadata:
36+
generateName: git-clone-
37+
spec:
38+
pipelineRef:
39+
name: git-clone-pipeline
40+
podTemplate:
41+
securityContext:
42+
fsGroup: 65532
43+
...
44+
...
45+
```
46+
47+
An example TaskRun will look like:
48+
```yaml
49+
apiVersion: tekton.dev/v1beta1
50+
kind: TaskRun
51+
metadata:
52+
name: taskrun
53+
spec:
54+
taskRef:
55+
name: git-clone
56+
podTemplate:
57+
securityContext:
58+
fsGroup: 65532
59+
...
60+
...
61+
```
62+
63+
* **output**: A workspace for this Task to fetch the git repository in to.
64+
* **ssh-directory**: An optional workspace to provide SSH credentials. At
65+
minimum this should include a private key but can also include other common
66+
files from `.ssh` including `config` and `known_hosts`. It is **strongly**
67+
recommended that this workspace be bound to a Kubernetes `Secret`.
68+
69+
* **ssl-ca-directory**: An optional workspace to provide custom CA certificates.
70+
Like the /etc/ssl/certs path this directory can have any pem or cert files,
71+
this uses libcurl ssl capath directive. See this SO answer here
72+
https://stackoverflow.com/a/9880236 on how it works.
73+
74+
* **basic-auth**: An optional workspace containing `.gitconfig` and
75+
`.git-credentials` files. This allows username/password/access token to be
76+
provided for basic auth.
77+
78+
It is **strongly** recommended that this workspace be bound to a Kubernetes
79+
`Secret`. For details on the correct format of the files in this Workspace
80+
see [Using basic-auth Credentials](#using-basic-auth-credentials) below.
81+
82+
**Note**: Settings provided as part of a `.gitconfig` file can affect the
83+
execution of `git` in ways that conflict with the parameters of this Task.
84+
For example, specifying proxy settings in `.gitconfig` could conflict with
85+
the `httpProxy` and `httpsProxy` parameters this Task provides. Nothing
86+
prevents you setting these parameters but it is not advised.
87+
88+
## Parameters
89+
90+
* **url**: Repository URL to clone from. (_required_)
91+
* **revision**: Revision to checkout. (branch, tag, sha, ref, etc...) (_default_: "")
92+
* **refspec**: Refspec to fetch before checking out revision. (_default_:"")
93+
* **submodules**: Initialize and fetch git submodules. (_default_: true)
94+
* **depth**: Perform a shallow clone, fetching only the most recent N commits. (_default_: 1)
95+
* **sslVerify**: Set the `http.sslVerify` global git config. Setting this to `false` is not advised unless you are sure that you trust your git remote. (_default_: true)
96+
* **crtFileName**: If `sslVerify` is **true** and `ssl-ca-directory` workspace is given then set `crtFileName` if mounted file name is different than `ca-bundle.crt`. (_default_: "ca-bundle.crt")
97+
* **subdirectory**: Subdirectory inside the `output` workspace to clone the repo into. (_default:_ "")
98+
* **deleteExisting**: Clean out the contents of the destination directory if it already exists before cloning. (_default_: true)
99+
* **httpProxy**: HTTP proxy server for non-SSL requests. (_default_: "")
100+
* **httpsProxy**: HTTPS proxy server for SSL requests. (_default_: "")
101+
* **noProxy**: Opt out of proxying HTTP/HTTPS requests. (_default_: "")
102+
* **verbose**: Log the commands that are executed during `git-clone`'s operation. (_default_: true)
103+
* **sparseCheckoutDirectories**: Which directories to match or exclude when performing a sparse checkout (_default_: "")
104+
* **gitInitImage**: The image providing the git-init binary that this Task runs. (_default_: "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/git-init:TODO")
105+
* **userHome**: The user's home directory. (_default_: "/tekton/home")
106+
107+
## Results
108+
109+
* **commit**: The precise commit SHA that was fetched by this Task
110+
* **url**: The precise URL that was fetched by this Task
111+
112+
## Platforms
113+
114+
The Task can be run on `linux/amd64`, `linux/s390x`, `linux/arm64`, and `linux/ppc64le` platforms.
115+
116+
## Usage
117+
118+
If the `revision` is not provided in the param of the taskrun
119+
then it will auto-detect the branch as specified by the `default`
120+
in the respective git repository.
121+
122+
The following pipelines demonstrate usage of the git-clone Task:
123+
124+
- [Cloning a branch](./samples/git-clone-checking-out-a-branch.yaml)
125+
- [Checking out a specific git commit](./samples/git-clone-checking-out-a-commit.yaml)
126+
- [Checking out a git tag and using the "commit" Task Result](./samples/using-git-clone-result.yaml)
127+
128+
## Cloning Private Repositories
129+
130+
This Task supports fetching private repositories. There are three ways to
131+
authenticate:
132+
133+
1. The simplest approach is to bind an `ssh-directory` workspace to this
134+
Task. The workspace should contain private keys (e.g. `id_rsa`), `config`
135+
and `known_hosts` files - anything you need to interact with your git remote
136+
via SSH. It's **strongly** recommended that you use Kubernetes `Secrets` to
137+
hold your credentials and bind to this workspace.
138+
139+
In a TaskRun that would look something like this:
140+
141+
```yaml
142+
kind: TaskRun
143+
spec:
144+
workspaces:
145+
- name: ssh-directory
146+
secret:
147+
secretName: my-ssh-credentials
148+
```
149+
150+
And in a Pipeline and PipelineRun it would look like this:
151+
152+
```yaml
153+
kind: Pipeline
154+
spec:
155+
workspaces:
156+
- name: ssh-creds
157+
# ...
158+
tasks:
159+
- name: fetch-source
160+
taskRef:
161+
name: git-clone
162+
workspaces:
163+
- name: ssh-directory
164+
workspace: ssh-creds
165+
# ...
166+
---
167+
kind: PipelineRun
168+
spec:
169+
workspaces:
170+
- name: ssh-creds
171+
secret:
172+
secretName: my-ssh-credentials
173+
# ...
174+
```
175+
176+
The `Secret` would appear the same in both cases - structured like a `.ssh`
177+
directory:
178+
179+
```yaml
180+
kind: Secret
181+
apiVersion: v1
182+
metadata:
183+
name: my-ssh-credentials
184+
data:
185+
id_rsa: # ... base64-encoded private key ...
186+
known_hosts: # ... base64-encoded known_hosts file ...
187+
config: # ... base64-encoded ssh config file ...
188+
```
189+
190+
Including `known_hosts` is optional but strongly recommended. Without it
191+
the `git-clone` Task will blindly accept the remote server's identity.
192+
193+
2. Use Tekton Pipelines' built-in credentials support as [documented in
194+
Pipelines' auth.md](https://github.com/tektoncd/pipeline/blob/master/docs/auth.md).
195+
196+
3. Another approach is to bind an `ssl-ca-directory` workspace to this
197+
Task. The workspace should contain crt keys (e.g. `ca-bundle.crt`)files - anything you need to interact with your git remote
198+
via custom CA . It's **strongly** recommended that you use Kubernetes `Secrets` to
199+
hold your credentials and bind to this workspace.
200+
201+
In a TaskRun that would look something like this:
202+
203+
```yaml
204+
kind: TaskRun
205+
spec:
206+
workspaces:
207+
- name: ssl-ca-directory
208+
secret:
209+
secretName: my-ssl-credentials
210+
```
211+
212+
And in a Pipeline and PipelineRun it would look like this:
213+
214+
```yaml
215+
kind: Pipeline
216+
spec:
217+
workspaces:
218+
- name: ssl-creds
219+
# ...
220+
tasks:
221+
- name: fetch-source
222+
taskRef:
223+
name: git-clone
224+
workspaces:
225+
- name: ssl-ca-directory
226+
workspace: ssl-creds
227+
# ...
228+
---
229+
kind: PipelineRun
230+
spec:
231+
workspaces:
232+
- name: ssl-creds
233+
secret:
234+
secretName: my-ssl-credentials
235+
# ...
236+
```
237+
238+
The `Secret` would appear like below:
239+
240+
```yaml
241+
kind: Secret
242+
apiVersion: v1
243+
metadata:
244+
name: my-ssl-credentials
245+
data:
246+
ca-bundle.crt: # ... base64-encoded crt ... # If key/filename is other than ca-bundle.crt then set crtFileName param as explained under Parameters section
247+
```
248+
249+
## Using basic-auth Credentials
250+
251+
**Note**: It is strongly advised that you use `ssh` credentials when the option
252+
is available to you before using basic auth. You can use generate a short
253+
lived token from WebVCS platforms (Github, Gitlab, Bitbucket etc..) to be use
254+
as password and generally be able to use `git` as the username.
255+
On bitbucket server the token may have a / into it so you would need
256+
to urlquote them before in the `Secret`, see this stackoverflow answer :
257+
258+
https://stackoverflow.com/a/24719496
259+
260+
To support basic-auth this Task exposes an optional `basic-auth` Workspace.
261+
The bound Workspace must contain a `.gitconfig` and `.git-credentials` file.
262+
Any other files on this Workspace are ignored. A typical `Secret` containing
263+
these credentials looks as follows:
264+
265+
```yaml
266+
kind: Secret
267+
apiVersion: v1
268+
metadata:
269+
name: my-basic-auth-secret
270+
type: Opaque
271+
stringData:
272+
.gitconfig: |
273+
[credential "https://<hostname>"]
274+
helper = store
275+
.git-credentials: |
276+
https://<user>:<pass>@<hostname>
277+
```
278+

0 commit comments

Comments
 (0)