feat(status): report skipped status for unmatched PipelineRuns

config/300-repositories.yaml

@@ -432,6 +432,36 @@ spec:
                             type: string
                           type: array
                       type: object
+                    status_checks:
+                      description: StatusChecks configures the status checks for the repository.
+                      properties:
+                        enabled:
+                          description: Enabled defines if the status checks should be reported. Default is false.
+                          type: boolean
+                        mode:
+                          description: |-
+                            Mode defines how the status checks should be reported when is enabled.
+                            Options:
+                            - 'per_pipelinerun': Report the status check of each PipelineRun separately.
+                          enum:
+                            - ""
+                            - per_pipelinerun
+                          type: string
+                        unmatched_conclusion:
+                          description: |-
+                            UnmatchedConclusion defines the conclusion to report when pipeline run is not matched. Default is 'skipped'.
+                            this will be used only if mode is 'per_pipelinerun'.
+                            Options:
+                            - 'success': Report as success.
+                            - 'neutral': Report as neutral.
+                            - 'skipped': Report as skipped. Default.
+                          enum:
+                            - ""
+                            - success
+                            - neutral
+                            - skipped
+                          type: string
+                      type: object
                   type: object
                 url:
                   description: |-

docs/content/docs/api/repository-spec.md

@@ -307,4 +307,7 @@ spec:
             container_logs:
               enabled: true
               max_lines: 100
+    status_checks:
+      enabled: true
+      mode: "per_pipelinerun"
 ```

docs/content/docs/api/repository.md

@@ -143,6 +143,9 @@ spec:
             container_logs:
               enabled: true
               max_lines: 100
+    status_checks:
+      enabled: true
+      mode: "per_pipelinerun"
 ```
 
 ## Related resources

docs/content/docs/api/settings.md

@@ -366,6 +366,60 @@ settings:
 {{< /param-group >}}
 {{< /param >}}
 
+## Status check settings
+
+{{< param name="status_checks" type="StatusCheck" >}}
+Configures status check reporting for PipelineRuns that did not match the incoming event. See the [Status Checks guide]({{< relref "/docs/guides/repository-crd/status-checks" >}}) for full details and provider behavior.
+
+{{< param-group label="Show StatusCheck Fields" >}}
+
+{{< param name="status_checks.enabled" type="boolean" id="param-status-check-enabled" >}}
+Enables or disables status check reporting for unmatched PipelineRuns. Default: `false`.
+
+```yaml
+settings:
+  status_checks:
+    enabled: true
+```
+
+{{< /param >}}
+
+{{< param name="status_checks.mode" type="string" id="param-status-check-mode" >}}
+Controls how status checks are reported. Options:
+
+- `per_pipelinerun` - Report a separate status for each unmatched PipelineRun
+
+```yaml
+settings:
+  status_checks:
+    mode: "per_pipelinerun"
+```
+
+{{< /param >}}
+
+{{< param name="status_checks.unmatched_conclusion" type="string" id="param-status-check-no-match-conclusion" >}}
+The conclusion to report for unmatched PipelineRuns. Only used when `mode` is `per_pipelinerun`. Default: `skipped`. Options: `skipped`, `success`, `neutral`.
+
+```yaml
+settings:
+  status_checks:
+    unmatched_conclusion: "skipped"
+```
+
+{{< /param >}}
+
+{{< /param-group >}}
+
+```yaml
+settings:
+  status_checks:
+    enabled: true
+    mode: "per_pipelinerun"
+    unmatched_conclusion: "skipped"
+```
+
+{{< /param >}}
+
 ## Complete example
 
 ```yaml
@@ -432,6 +486,12 @@ spec:
           context_items:
             commit_content: true
             pr_content: true
+
+    # Status check reporting
+    status_checks:
+      enabled: true
+      mode: "per_pipelinerun"
+      unmatched_conclusion: "skipped"
 ```
 
 ## Settings inheritance

docs/content/docs/guides/_index.md

@@ -9,7 +9,7 @@ This section covers the core workflows you need to run CI/CD with Pipelines-as-C
 
 {{< cards >}}
   {{< card link="creating-pipelines" title="Authoring PipelineRuns" subtitle="Create pipelines, CEL variables, GitHub token" >}}
-  {{< card link="repository-crd" title="Repository CR" subtitle="Configure repos, concurrency, comment settings" >}}
+  {{< card link="repository-crd" title="Repository CR" subtitle="Configure repos, concurrency, comment settings, status checks" >}}
   {{< card link="event-matching" title="Event matching" subtitle="on-event, on-target-branch, path, CEL, labels" >}}
   {{< card link="gitops-commands" title="GitOps commands" subtitle="/retest, /test, /cancel and more" >}}
   {{< card link="statuses" title="PipelineRun status" subtitle="Status reporting and failure detection" >}}

docs/content/docs/guides/repository-crd/status-checks.md

@@ -0,0 +1,105 @@
+---
+title: Status Checks
+weight: 5
+---
+
+{{< tech_preview "Status Checks settings in Repository CR" >}}
+
+This page explains how to report status checks for PipelineRuns that did not match the incoming event. Use this when you want visibility into which PipelineRuns in your `.tekton/` directory were skipped because their annotations (target branch, event type, CEL expression, or path filter) did not match.
+
+By default, Pipelines-as-Code only reports status for PipelineRuns that matched
+and ran. PipelineRuns that did not match are silently ignored. Enabling
+`status_checks` makes Pipelines-as-Code report a status for each unmatched
+PipelineRun so you can see the full picture in your Git provider's UI.
+
+## Configuration
+
+Add the `status_checks` block under `spec.settings` in your Repository CR:
+
+```yaml
+apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
+kind: Repository
+metadata:
+  name: my-repo
+spec:
+  url: "https://github.com/owner/repo"
+  settings:
+    status_checks:
+      enabled: true
+      mode: "per_pipelinerun"
+```
+
+### Fields
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | bool | `false` | Enable status check reporting for unmatched PipelineRuns. |
+| `mode` | string | | How to report status checks. See [Modes](#modes). |
+| `unmatched_conclusion` | string | `skipped` | The conclusion to report for unmatched PipelineRuns. Only used when `mode` is `per_pipelinerun`. Accepted values: `skipped`, `success`, `neutral`. |
+
+### Modes
+
+#### `per_pipelinerun`
+
+Reports a separate status for each PipelineRun that did not match the event.
+This is useful when you have multiple PipelineRuns targeting different events
+(for example, one for `pull_request` and one for `push`) and you want to see
+which ones were skipped on each event.
+
+```yaml
+spec:
+  settings:
+    status_checks:
+      enabled: true
+      mode: "per_pipelinerun"
+```
+
+### Customizing the conclusion
+
+By default, unmatched PipelineRuns are reported with a `skipped` conclusion.
+You can change this to `success` or `neutral` using the `unmatched_conclusion`
+field:
+
+```yaml
+spec:
+  settings:
+    status_checks:
+      enabled: true
+      mode: "per_pipelinerun"
+      unmatched_conclusion: "success"
+```
+
+## Provider behavior
+
+The `skipped` conclusion maps to different states depending on your Git provider:
+
+| Provider | Reported state | Notes |
+| --- | --- | --- |
+| GitHub App | `skipped` | Shown as a skipped check run. |
+| GitHub Webhook | `success` | GitHub commit status API does not support `skipped`. Reported as `success` with a "Skipped" description. |
+| GitLab | `skipped` | Shown as a skipped pipeline in the Pipelines tab. |
+| Bitbucket Cloud | `STOPPED` | Shown as a stopped build status. |
+| Bitbucket Data Center | `UNKNOWN` | Reported with an unknown state. |
+| Gitea / Forgejo | `success` | Gitea does not support `skipped`. Reported as `success` with a "Skipped" description. |
+
+## Example
+
+Consider a repository with two PipelineRuns:
+
+- `.tekton/build.yaml` -- targets `pull_request` events on the `main` branch
+- `.tekton/deploy.yaml` -- targets `push` events on the `main` branch
+
+When a pull request is opened, `build.yaml` matches and runs. Without
+`status_checks`, `deploy.yaml` is silently ignored. With it enabled:
+
+```yaml
+spec:
+  settings:
+    status_checks:
+      enabled: true
+      mode: "per_pipelinerun"
+```
+
+Pipelines-as-Code reports a `skipped` status for `deploy.yaml`, making it
+visible in the pull request's status checks that the PipelineRun exists but did
+not apply to this event.

docs/content/docs/guides/statuses.md

@@ -113,6 +113,10 @@ You can use the `tkn pac describe` command from the [CLI]({{< relref "/docs/cli/
 all statuses of PipelineRuns associated with your repository and
 their metadata.
 
+## Status checks for unmatched PipelineRuns
+
+By default, Pipelines-as-Code only reports status for PipelineRuns that matched and ran. If you want to see which PipelineRuns were skipped because their annotations did not match the incoming event, enable the `status_checks` setting in your Repository CR. See the [Status Checks guide]({{< relref "/docs/guides/repository-crd/status-checks" >}}) for configuration and provider behavior.
+
 ## Notifications
 
 Pipelines-as-Code does not manage notifications directly. Instead, you can add notifications to your PipelineRuns using the [finally feature of

docs/content/docs/operations/global-repository-settings.md

@@ -32,6 +32,7 @@ You can define the following settings in the global Repository CR:
   - The `type` must be defined in the namespace repository settings and must match the `type` of the global repository (see below for an example).
 - [Custom Parameters]({{< relref "/docs/advanced/custom-parameters" >}}).
 - [Incoming Webhooks Rules]({{< relref "/docs/advanced/incoming-webhooks" >}}).
+- [Status Checks]({{< relref "/docs/guides/repository-crd/status-checks" >}}).
 
 {{< callout type="info" >}}
 Global settings are only applied when running via a Git provider event; they are not applied when for example using the `tkn pac` cli.

pkg/apis/pipelinesascode/v1alpha1/types.go

@@ -4,6 +4,10 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
+const (
+	StatusCheckModePerPipelineRun = "per_pipelinerun"
+)
+
 // +genclient
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
@@ -135,6 +139,10 @@ type Settings struct {
 	// AIAnalysis contains AI/LLM analysis configuration for automated CI/CD pipeline analysis.
 	// +optional
 	AIAnalysis *AIAnalysisConfig `json:"ai,omitempty"`
+
+	// StatusChecks configures the status checks for the repository.
+	// +optional
+	StatusChecks *StatusChecks `json:"status_checks,omitempty"`
 }
 
 type GitlabSettings struct {
@@ -182,6 +190,30 @@ type ForgejoSettings struct {
 	CommentStrategy string `json:"comment_strategy,omitempty"`
 }
 
+// StatusChecks configures the status checks for the repository.
+type StatusChecks struct {
+	// Enabled defines if the status checks should be reported. Default is false.
+	// +optional
+	Enabled bool `json:"enabled,omitempty"`
+
+	// Mode defines how the status checks should be reported when is enabled.
+	// Options:
+	// - 'per_pipelinerun': Report the status check of each PipelineRun separately.
+	// +optional
+	// +kubebuilder:validation:Enum="";per_pipelinerun
+	Mode string `json:"mode,omitempty"`
+
+	// UnmatchedConclusion defines the conclusion to report when pipeline run is not matched. Default is 'skipped'.
+	// this will be used only if mode is 'per_pipelinerun'.
+	// Options:
+	// - 'success': Report as success.
+	// - 'neutral': Report as neutral.
+	// - 'skipped': Report as skipped. Default.
+	// +optional
+	// +kubebuilder:validation:Enum="";success;neutral;skipped
+	UnmatchedConclusion string `json:"unmatched_conclusion,omitempty"`
+}
+
 func (s *Settings) Merge(newSettings *Settings) {
 	if newSettings.PipelineRunProvenance != "" && s.PipelineRunProvenance == "" {
 		s.PipelineRunProvenance = newSettings.PipelineRunProvenance
@@ -211,6 +243,10 @@ func (s *Settings) Merge(newSettings *Settings) {
 	if newSettings.GitOpsCommandPrefix != "" && s.GitOpsCommandPrefix == "" {
 		s.GitOpsCommandPrefix = newSettings.GitOpsCommandPrefix
 	}
+
+	if newSettings.StatusChecks != nil && s.StatusChecks == nil {
+		s.StatusChecks = newSettings.StatusChecks
+	}
 }
 
 func (s *GitlabSettings) Merge(newSettings *GitlabSettings) {