|
| 1 | +--- |
| 2 | +title: "Using PaC's `git_auth_secret` to Avoid Rate Limiting" |
| 3 | +date: 2025-07-30 |
| 4 | +--- |
| 5 | + |
| 6 | +## Using PaC's `git_auth_secret` to Avoid Rate Limiting |
| 7 | + |
| 8 | +When Tekton pipelines fetch resources like `Tasks` or `Pipelines` from a Git repository using the **`git` resolver**, frequent unauthenticated requests can lead to **rate limiting** from your Git provider. For private repositories, this fetching would fail entirely without authentication. |
| 9 | + |
| 10 | +Pipelines-as-Code (PaC) solves this elegantly by automatically generating a temporary, scoped authentication token for each `PipelineRun`. This token is stored in a Kubernetes `Secret`, and its name is made available to your `PipelineRun` through the built-in `{{ git_auth_secret }}` variable. |
| 11 | + |
| 12 | +This guide shows how to use `{{ git_auth_secret }}` to enable authenticated Git operations with the `git` resolver, helping you avoid rate-limiting and access private resources securely. |
| 13 | + |
| 14 | +### How It Works |
| 15 | + |
| 16 | +For each `PipelineRun`, Pipelines-as-Code performs these actions automatically: |
| 17 | + |
| 18 | +1. **Generates a Token**: It creates a short-lived, scoped token for your Git provider. |
| 19 | +2. **Creates a Secret**: It creates a `Secret` in the target namespace to hold the token. The secret name is unique for each run (e.g., `pac-gitauth-owner-repo-xxxx`, where `xxxx` is a unique suffix generated for the run, typically consisting of random characters or a hash). |
| 20 | +3. **Injects the Variable**: It makes the secret's name available in your `.tekton/` templates via the `{{ git_auth_secret }}` variable. |
| 21 | + |
| 22 | +This secret is owned by the `PipelineRun` and is automatically garbage-collected when the `PipelineRun` is deleted. You can learn more about this mechanism in the [Private Repositories documentation]({{< relref "/docs/guide/privaterepo.md" >}}). |
| 23 | + |
| 24 | +### Step 1: Design Your Pipeline for Authentication |
| 25 | + |
| 26 | +First, ensure your `Pipeline` is designed to accept a secret name as a parameter. The `taskRef` using the `git` resolver must be configured to use this parameter for authentication. |
| 27 | + |
| 28 | +Your `pipeline.yaml` should look like this: |
| 29 | + |
| 30 | +```yaml |
| 31 | +--- |
| 32 | +apiVersion: tekton.dev/v1 |
| 33 | +kind: Pipeline |
| 34 | +metadata: |
| 35 | + name: my-pipeline |
| 36 | +spec: |
| 37 | + params: |
| 38 | + # This parameter will receive the secret name from the PipelineRun via the PaC `{{ git_auth_secret }}` variable |
| 39 | + - name: git-auth-secret |
| 40 | + description: The name of the Kubernetes secret for Git authentication. |
| 41 | + type: string |
| 42 | + |
| 43 | + # Other parameters for your pipeline |
| 44 | + - name: git-repo-url |
| 45 | + type: string |
| 46 | + - name: git-revision |
| 47 | + type: string |
| 48 | + tasks: |
| 49 | + - name: fetch-remote-task |
| 50 | + taskRef: |
| 51 | + resolver: git |
| 52 | + params: |
| 53 | + - name: url |
| 54 | + value: $(params.git-repo-url) |
| 55 | + - name: revision |
| 56 | + value: $(params.git-revision) |
| 57 | + - name: pathInRepo |
| 58 | + value: path/to/your/task.yaml |
| 59 | + # --- Authentication Parameters --- |
| 60 | + # Use the pipeline parameter to reference the secret name |
| 61 | + - name: http-auth-secret |
| 62 | + value: $(params.git-auth-secret) |
| 63 | +``` |
| 64 | +
|
| 65 | +### Step 2: Use `{{ git_auth_secret }}` in Your PipelineRun |
| 66 | + |
| 67 | +You do not need to create any secrets manually. Simply reference the PaC variable `{{ git_auth_secret }}` in your `PipelineRun` template file (e.g., `.tekton/pipelinerun.yaml`). |
| 68 | + |
| 69 | +PaC will substitute this placeholder with the name of the auto-generated secret at runtime. |
| 70 | + |
| 71 | +```yaml |
| 72 | +# .tekton/pipelinerun.yaml |
| 73 | +
|
| 74 | +apiVersion: tekton.dev/v1 |
| 75 | +kind: PipelineRun |
| 76 | +metadata: |
| 77 | + generateName: my-pipelinerun- |
| 78 | +spec: |
| 79 | + pipelineRef: |
| 80 | + name: my-pipeline |
| 81 | + params: |
| 82 | + # Pass the PaC variable to your pipeline's parameter |
| 83 | + - name: git-auth-secret |
| 84 | + value: "{{ git_auth_secret }}" |
| 85 | +
|
| 86 | + # Pass other necessary parameters |
| 87 | + - name: git-repo-url |
| 88 | + value: "{{ repo_url }}" |
| 89 | + - name: git-revision |
| 90 | + value: "{{ revision }}" |
| 91 | +``` |
| 92 | + |
| 93 | +By following this pattern, your remote tasks will be fetched using an authenticated session managed entirely by Pipelines-as-Code. |
| 94 | + |
| 95 | +### Beyond Task Resolution |
| 96 | + |
| 97 | +The `{{ git_auth_secret }}` is versatile. Besides its use with the `git` resolver, it can also be used for: |
| 98 | + |
| 99 | +- **Cloning private repositories**: Use the secret as a `workspace` for the `git-clone` task. |
| 100 | +- **Calling the Git provider API**: Use the token within the secret to make API calls, for example, to post a comment back to a pull request. |
| 101 | + |
| 102 | +For more examples and details, see the documentation on [Authoring PipelineRuns]({{< relref "/docs/guide/authoringprs.md#using-the-temporary-github-app-token-for-github-api-operations" >}}). |
0 commit comments