Pipelines-as-Code resolver #

Pipelines-as-Code resolver ensures the PipelineRun you are running does not conflicts with others.

If Pipelines-as-Code sees a PipelineRun with a reference to a Task or to a Pipeline in any YAML file located in the .tekton/ directory it will automatically try to resolves it (see below) as a single PipelineRun with an embedded PipelineSpec to a PipelineRun.

The resolver will then transform the Pipeline Name field to a GenerateName based on the Pipeline name as well.

If you want to split your Pipeline and PipelineRun, you can store the files in the .tekton/ directory or its subdirectories. Pipeline and Task can as well be referenced remotely (see below on how the remote tasks are referenced).

The resolver will skip resolving if it sees these type of tasks:

• a reference to a ClusterTask
• a Task or Pipeline Bundle
• a reference to a Tekton Resolver
• a Custom Task with an apiVersion that doesn’t have a tekton.dev/ prefix.

It just uses them “as is” and will not try to do anything with it.

If Pipelines-as-Code cannot resolve the referenced tasks in the Pipeline or PipelineSpec, the run will fail before applying the pipelinerun onto the cluster.

You should be able to see the issue on your Git provider platform interface and inside the events of the target namespace where the Repository CR is located.

If you need to test your PipelineRun locally before sending it in a PR, you can use the resolve command from the tkn-pac CLI See CLI command to learn on how to use it.

Remote Task annotations #

Pipelines-as-Code support fetching remote tasks or pipeline from a remote location with annotations on PipelineRun.

If the resolver sees a PipelineRun referencing a remote task or a Pipeline in a PipelineRun or a PipelineSpec it will automatically inlines them.

If multiple annotations reference the same task name the resolver will pick the first one fetched from the annotations.

An annotation to a remote task looks like this :

pipelinesascode.tekton.dev/task: "git-clone"

or multiple tasks with an array :

pipelinesascode.tekton.dev/task: "[git-clone, pylint]"

Tekton Hub #

pipelinesascode.tekton.dev/task: "git-clone"

The syntax above installs the git-clone task from the tekton hub repository querying for the latest version with the tekton hub API.

You can have multiple tasks in there if you separate them by a comma , around an array syntax with bracket:

pipelinesascode.tekton.dev/task: "[git-clone, golang-test, tkn]"

You can have multiple lines if you add a -NUMBER suffix to the annotation, for example :

  pipelinesascode.tekton.dev/task: "git-clone"
  pipelinesascode.tekton.dev/task-1: "golang-test"
  pipelinesascode.tekton.dev/task-2: "tkn"

By default, Pipelines-as-Code will interpret the string as the latest task to grab from tekton hub.

If you want to have a specific version of the task, you can add a colon : to the string and a version number, like in this example :

pipelinesascode.tekton.dev/task: "[git-clone:0.1]" # this will install git-clone 0.1 from tekton.hub

Custom Tekton Hub #

Additionally if the cluster administrator has set-up a custom Tekton Hub you are able to reference it from your template like this example:

pipelinesascode.tekton.dev/task: "[anothercatalog://curl]" # this will install curl from the custom catalog configured by the cluster administrator as anothercatalog

There is no fallback to the default Tekton Hub if the custom Tekton Hub does not have the task referenced it will fail.

There is no support for custom hub from the CLI on the tkn pac resolver command.

Remote HTTP URL #

If you have a string starting with http:// or https://, Pipelines-as-Code will fetch the task directly from that remote URL :

  pipelinesascode.tekton.dev/task: "[https://remote.url/task.yaml]"

Remote HTTP URL from a private GitHub repository #

If you are using GitHub and If the remote task URL uses the same host as where the repo CRD is, PAC will use the GitHub token and fetch the URL using the GitHub API.

For example if you have a repo URL looking like this :

https://github.com/organization/repository

and the remote HTTP URLs is a referenced GitHub “blob” URL:

https://github.com/organization/repository/blob/mainbranch/path/file

if the remote HTTP url has a slash (/) in the branch name you will need to html encode with the %2F character, eg:

https://github.com/organization/repository/blob/feature%2Fmainbranch/path/file

It will be use the GitHub API with the generated token to fetch that file. This allows you to reference a task or a pipeline from a private repository easily.

GitHub app token are scoped to the owner or organization where the repository is located. If you are using the GitHub webhook method you are able to fetch any private or public repositories on any organization where the personal token is allowed.

There is settings you can set in the pac Configmap to control that behavior, see the secret-github-app-token-scoped and secret-github-app-scope-extra-repos settings in the settings documentation.

Tasks or Pipelines inside the repository #

Additionally, you can as well have a reference to a task or pipeline from a YAML file inside your repo if you specify the relative path to it, for example :

pipelinesascode.tekton.dev/task: "[share/tasks/git-clone.yaml]"

This will grab the file share/tasks/git-clone.yaml from the current repository on the SHA where the event come from (i.e: the current pull request or the current branch push).

If there is any error fetching those resources, Pipelines-as-Code will error out and not process the pipeline.

If the object fetched cannot be parsed as a Tekton Task it will error out.

Remote Pipeline annotations #

Remote Pipeline can be referenced by annotation, this allows you to share your Pipeline definition across.

Only one Pipeline is allowed in annotation.

An annotation to a remote pipeline looks like this :

pipelinesascode.tekton.dev/pipeline: "https://git.provider/raw/pipeline.yaml

It supports remote URL and files inside the same Git repository.

Tekton Hub doesn’t currently have support for Pipeline.