Story (Required)

As a developer using Pipelines-as-Code, I want to reference remote StepActions in my PipelineRun so that I can reuse common sequences of steps across multiple repositories and keep my pipeline definitions DRY.

This feature allows for the creation of reusable, standalone sequences of steps (e.g., for building, testing, or deploying). It improves maintainability by abstracting common logic into versionable, remote StepActions. This approach leverages the existing Pipelines-as-Code infrastructure, making it easy for users to fetch resources (including from private repositories) via a simple annotation and reusing PaC's temporary tokens, without needing to configure the Tekton Resolver. This enhancement is strictly limited to `tekton.dev/v1` PipelineRuns.

Background (Required)

Tekton's `StepAction` resource (`tekton.dev/v1alpha1`) provides a way to define a reusable sequence of steps. While Tekton has its own resolver framework, implementing this fetch mechanism directly within Pipelines-as-Code offers a significantly simpler and more integrated user experience.

By using a simple annotation, users can leverage the existing PaC permission model and the temporary tokens (e.g., GitHub App token) generated for the runtime. This enables seamless and secure access to `StepAction`s stored in private repositories with no additional authentication configuration required from the user. A critical requirement is to enforce that this feature is only available for `PipelineRun` resources using `apiVersion: tekton.dev/v1` to ensure compatibility and promote best practices.

Out of scope

• Support for `tekton.dev/v1beta1` `PipelineRun` resources. These will be explicitly blocked.
• Support for fetching any remote resource type other than `tekton.dev/v1alpha1` `StepAction`.
• Parameter substitution or modification of the fetched `StepAction` content.

Approach (Required)

The implementation will involve the following steps:

1. New Annotation: Introduce the `pipelinesascode.tekton.dev/stepaction` annotation. The parsing logic in `pkg/matcher/annotation_tasks_install.go` will be updated to handle it.

2. Version Validation: The core enforcement will happen in the resolver (`pkg/resolve/resolve.go`).

• As the resolver processes `PipelineRun` manifests, it must check the `apiVersion`.
• If a `PipelineRun` contains the `.../stepaction` annotation but its original version is `tekton.dev/v1beta1`, the resolution process will fail immediately with an informative error message.
• This can be achieved by adding a temporary internal annotation (e.g., `pipelinesascode.tekton.dev/original-version: v1beta1`) during the `v1beta1`->`v1` conversion process, which the resolver can then check for.

3. Fetching and Inlining: For valid `tekton.dev/v1` `PipelineRun`s:

• The resolver will fetch the `StepAction` resources from the locations specified in the annotation (URL, in-repo path, etc.), reusing the PaC client for authentication.
• During `Task` resolution, any step that uses a `ref` pointing to a fetched `StepAction`'s name (e.g., `ref.name: my-reusable-steps`) will be replaced by the sequence of steps defined in that `StepAction`'s `spec.steps`.

Example Usage:

A user's `.tekton/pipelinerun.yaml`:

# This MUST be a v1 PipelineRun
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata: 
  name: my-pipelinerun
  annotations: 
    pipelinesascode.tekton.dev/stepaction: "https://github.com/private/repo/tree/main/my-step-action.yaml" # will fetch from github using temporary github that have access to the private repo
    pipelinesascode.tekton.dev/stepaction-1: "[git-clone, pylint]" # will fetch git-clone task and pylint from artifacthub
spec: 
  pipelineSpec: 
    tasks: 
      - name: build-the-thing
        taskSpec: 
          steps: 
            # This step will be replaced by the steps from the remote StepAction
            - ref: 
                name: my-reusable-build-steps

Dependencies

• This feature depends on the existence of the `StepAction` CRD (`tekton.dev/v1alpha1`) in the target cluster.

Acceptance Criteria (Mandatory)

• A new annotation `pipelinesascode.tekton.dev/stepaction` is available and can be used multiple times with numeric suffixes (e.g., `.../stepaction-1`, `.../stepaction-2`).
• The resolution MUST fail with a clear error message if the `.../stepaction` annotation is used on a `PipelineRun` with an `apiVersion` of `tekton.dev/v1beta1`.
• For `v1` `PipelineRun`s, the resolver can fetch `StepAction` YAML from remote URLs, in-repo paths, or an Artifact Hub.
• The resolver transparently uses existing PaC credentials (e.g., temporary GitHub token) to fetch `StepAction`s from private sources.
• The fetched content is parsed as a `tekton.dev/v1alpha1.StepAction`.
• When resolving a `Task`, any step that references a fetched `StepAction` via `step.ref` is replaced by the sequence of steps from that `StepAction`.
• If a referenced `StepAction` cannot be found among the fetched resources, the run fails with a clear error message.

INVEST Checklist

Dependencies identified

Blockers noted and expected delivery timelines set

Design is implementable

Acceptance criteria agreed upon

Story estimated

Legend

Unknown

Verified

Unsatisfied

Done Checklist

• [ ] Code is completed, reviewed, documented and checked in
• [ ] Unit and integration test automation have been delivered and running cleanly in continuous integration/staging/canary environment
• [ ] Continuous Delivery pipeline(s) is able to proceed with new code included
• [ ] Customer facing documentation, API docs etc. are produced/updated, reviewed and published
• [ ] Acceptance criteria are met