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.

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.1 version of the git-clone remote 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.
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.

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.

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
    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.