Chapter 5. Using the Pipelines as Code resolver
The Pipelines as Code resolver ensures that a running pipeline run does not conflict with others.
5.1. About the Pipelines as Code resolver
To split your pipeline and pipeline run, store the files in the .tekton/ directory or its subdirectories.
If Pipelines as Code observes a pipeline run with a reference to a task or a pipeline in any YAML file located in the .tekton/ directory, Pipelines as Code automatically resolves the referenced task to provide a single pipeline run with an embedded spec in a PipelineRun object.
If Pipelines as Code cannot resolve the referenced tasks in the Pipeline or PipelineSpec definition, the run fails before applying any changes to the cluster. You can see the issue on your Git provider platform and inside the events of the target namespace where the Repository CR is located.
The resolver skips resolving if it observes the following type of tasks:
- A reference to a cluster task.
- A task or pipeline bundle.
-
A custom task with an API version that does not have a
tekton.dev/prefix.
The resolver uses such tasks literally, without any transformation.
To test your pipeline run locally before sending it in a pull request, use the tkn pac resolve command.
You can also reference remote pipelines and tasks.
5.2. Using remote task annotations with Pipelines as Code
Pipelines as Code supports fetching remote tasks or pipelines by using annotations in a pipeline run. If you reference a remote task in a pipeline run, or a pipeline in a PipelineRun or a PipelineSpec object, the Pipelines as Code resolver automatically includes it. If there is any error while fetching the remote tasks or parsing them, Pipelines as Code stops processing the tasks.
To include remote tasks, refer to the following examples of annotation:
Reference remote tasks in Tekton Hub
Reference a single remote task in Tekton Hub.
... pipelinesascode.tekton.dev/task: "git-clone" 1 ...- 1
- Pipelines as Code includes the latest version of the task from the Tekton Hub.
Reference multiple remote tasks from Tekton Hub
... pipelinesascode.tekton.dev/task: "[git-clone, golang-test, tkn]" ...
Reference multiple remote tasks from Tekton Hub using the
-<NUMBER>suffix.... pipelinesascode.tekton.dev/task: "git-clone" pipelinesascode.tekton.dev/task-1: "golang-test" pipelinesascode.tekton.dev/task-2: "tkn" 1 ...- 1
- By default, Pipelines as Code interprets the string as the latest task to fetch from Tekton Hub.
Reference a specific version of a remote task from Tekton Hub.
... pipelinesascode.tekton.dev/task: "[git-clone:0.1]" 1 ...- 1
- Refers to the
0.1version of thegit-cloneremote task from Tekton Hub.
Remote tasks using URLs
...
pipelinesascode.tekton.dev/task: "<https://remote.url/task.yaml>" 1
...
- 1
- The public URL to the remote task.Note
If you use GitHub and the remote task URL uses the same host as the
Repositorycustom resource definition (CRD), Pipelines as Code uses the GitHub token and fetches the URL using the GitHub API.For example, if you have a repository URL similar to
https://github.com/<organization>/<repository>and the remote HTTP URL references a GitHub blob similar tohttps://github.com/<organization>/<repository>/blob/<mainbranch>/<path>/<file>, Pipelines as Code fetches the task definition files from that private repository with the GitHub App token.When you work on a public GitHub repository, Pipelines as Code acts similarly for a GitHub raw URL such as
https://raw.githubusercontent.com/<organization>/<repository>/<mainbranch>/<path>/<file>.- GitHub App tokens are scoped to the owner or organization where the repository is located. When you use the GitHub webhook method, you can fetch any private or public repository on any organization where the personal token is allowed.
Reference a task from a YAML file inside your repository
...
pipelinesascode.tekton.dev/task: "<share/tasks/git-clone.yaml>" 1
...
- 1
- Relative path to the local file containing the task definition.
5.3. Using remote pipeline annotations with Pipelines as Code
You can share a pipeline definition across multiple repositories by using the remote pipeline annotation.
...
pipelinesascode.tekton.dev/pipeline: "<https://git.provider/raw/pipeline.yaml>" 1
...- 1
- URL to the remote pipeline definition. You can also provide locations for files inside the same repository.
You can reference only one pipeline definition using the annotation.
5.3.1. Overriding a task in a remote pipeline
By default, if you use a remote pipeline annotation in a pipeline run, Pipelines as Code uses all the tasks that are a part of the remote pipeline.
You can override a task in a remote pipeline by adding a task annotation to the pipeline run. The added task must have the same name as a task in the remote pipeline.
For example, you might use the following pipeline run definition:
Example pipeline run definition referencing a remote pipeline and overriding a task
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
annotations:
pipelinesascode.tekton.dev/pipeline: "https://git.provider/raw/pipeline.yaml"
pipelinesascode.tekton.dev/task: "./my-git-clone-task.yaml"
For this example, assume the remote task found at https://git.provider/raw/pipeline.yaml includes a task named git-clone and the task that the my-git-clone-task.yaml file defines is also named git-clone.
In this case, the pipeline run executes the remote pipeline, but replaces the task named git-clone in the pipeline with the task you defined.
