feat(status): report skipped status for unmatched PipelineRuns

[zakisk]

📝 Description of the Change

When a repository has multiple PipelineRuns in .tekton/ targeting different events, only the ones matching the incoming event run. The rest are silently ignored, leaving gaps in the Git provider's status checks UI.

For example, a repository with two PipelineRuns:

.tekton/build.yaml — on-event: pull_request, on-target-branch: main
.tekton/deploy.yaml — on-event: push, on-target-branch: main

When a pull request is opened, build.yaml matches and runs. Without this feature, deploy.yaml produces no status at all — it is impossible to tell from the PR whether it was skipped intentionally or never picked up. With status_check enabled:

spec:
settings:
status_check:
enabled: true
mode: "per_unmatched_pipelinerun"

Pipelines-as-Code now reports a "skipped" status for deploy.yaml on the pull request, making the full picture visible in the provider UI.

The matcher now returns both matched and unmatched PipelineRuns. After the matched runs complete, the controller iterates the unmatched list and calls CreateStatus on each with the configured conclusion. The conclusion defaults to skipped but can be set to success or neutral via the no_match_conclusion field.

Every provider maps that conclusion to its native state:

• GitHub App: check run conclusion "skipped"
• GitHub Webhook: commit status "success" (API has no skipped)
• GitLab: pipeline status "skipped"
• Bitbucket Cloud: build status "STOPPED"
• Bitbucket Data Center: build status "UNKNOWN"
• Gitea/Forgejo: commit status "success" (no skipped state)

The setting is inheritable from the global Repository CR via the existing Settings.Merge path. A second mode (aggregate) is defined in the CRD but not yet implemented.

The whole feature is behind an opt-in flag (enabled: false by default) and marked as tech preview in the documentation.

🔗 Linked GitHub Issue

Fixes #

🧪 Testing Strategy

• Unit tests
• Integration tests
• End-to-end tests
• Manual testing
• Not Applicable

🤖 AI Assistance

AI assistance can be used for various tasks, such as code generation,
documentation, or testing.

Please indicate whether you have used AI assistance
for this PR and provide details if applicable.

• I have not used any AI assistance for this PR.
• I have used AI assistance for this PR. (For testing)

Important

Slop will be simply rejected, if you are using AI assistance you need to make sure you
understand the code generated and that it meets the project's standards. you
need at least know how to run the code and deploy it (if needed). See
startpaac to make it easy
to deploy and test your code changes.

If the majority of the code in this PR was generated by an AI, please add a Co-authored-by trailer to your commit message.
For example:

Co-authored-by: Claude noreply@anthropic.com

✅ Submitter Checklist

• 📝 My commit messages are clear, informative, and follow the project's How to write a git commit message guide. The Gitlint linter ensures in CI it's properly validated
• ✨ I have ensured my commit message prefix (e.g., fix:, feat:) matches the "Type of Change" I selected above.
• ♽ I have run make test and make lint locally to check for and fix any
  issues. For an efficient workflow, I have considered installing
  pre-commit and running pre-commit install to
  automate these checks.
• 📖 I have added or updated documentation for any user-facing changes.
• 🧪 I have added sufficient unit tests for my code changes.
• 🎁 I have added end-to-end tests where feasible. See README for more details.
• 🔎 I have addressed any CI test flakiness or provided a clear reason to bypass it.
• If adding a provider feature, I have filled in the following and updated the provider documentation:
  • GitHub App
  • GitHub Webhook
  • Gitea/Forgejo
  • GitLab
  • Bitbucket Cloud
  • Bitbucket Data Center

[codecov]

Codecov Report

❌ Patch coverage is 77.87611% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.84%. Comparing base (707a00d) to head (d7a4b71).

Files with missing lines	Patch %	Lines
pkg/pipelineascode/match.go	61.11%	13 Missing and 1 partial ⚠️
pkg/matcher/annotation_matcher.go	80.00%	4 Missing ⚠️
pkg/provider/gitea/gitea.go	42.85%	4 Missing ⚠️
pkg/provider/gitlab/gitlab.go	0.00%	1 Missing and 1 partial ⚠️
pkg/provider/github/status.go	88.88%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2918      +/-   ##
==========================================
+ Coverage   80.70%   80.84%   +0.14%     
==========================================
  Files         164      164              
  Lines       13907    13968      +61     
==========================================
+ Hits        11223    11292      +69     
+ Misses       1964     1957       -7     
+ Partials      720      719       -1     

Flag	Coverage Δ
unit-tests	80.84% <77.87%> (+0.14%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[pipelines-as-code]

Paco Review 🔍

This PR adds a new StatusCheck setting to the Repository CRD that lets users report a status (default: skipped) for PipelineRuns that did not match the incoming event. It threads a new unmatchedPRs return value through MatchPipelinerunByAnnotation and the pipelineascode match/run pipeline, adds a reportStatusCheckFromRepoSettings reporter that fires per-provider CreateStatus calls, updates several providers' handling of the skipped conclusion, and adds extensive unit/e2e tests and documentation.

Review difficulty: 4/5 (Hard) — The change spans the matcher core logic, the pipeline orchestration flow, and status-reporting code for five different Git providers, with several interacting control-flow changes that are easy to get subtly wrong.

2 new inline comment(s) found.

_{Reviewed commit: e2008a9}

[pipelines-as-code]

Paco inline comments -- see the Paco Review summary comment for the overview.

[zakisk]

/paco review

[zakisk]

I can't request review from copilot. cc: @chmouel

[pipelines-as-code]

Paco inline comments -- see the Paco Review summary comment for the overview.

[Copilot]

Pull request overview

Adds an opt-in “status_check” feature to report provider statuses for PipelineRuns that do not match the incoming event, improving visibility in Git provider UIs when multiple .tekton/ PipelineRuns target different triggers.

Changes:

• Extend PipelineRun matching to return both matched and unmatched PipelineRuns, and (when enabled) report a “skipped/success/neutral” status for each unmatched PipelineRun.
• Update provider-specific status mapping/formatting to support a “skipped” conclusion (or best-effort equivalents where unsupported).
• Add unit/E2E test coverage and documentation/CRD updates for the new Repository spec.settings.status_check API.

Reviewed changes

Copilot reviewed 35 out of 36 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/pkg/bitbucketdatacenter/crd.go	Pass Settings into Bitbucket DC E2E Repository CR creation.
test/pkg/bitbucketcloud/crd.go	Pass Settings into Bitbucket Cloud E2E Repository CR creation.
test/gitlab_merge_request_test.go	Add E2E coverage for skipped status reporting on GitLab MR.
test/github_pullrequest_test.go	Add E2E coverage for skipped status reporting (GitHub App + webhook).
test/gitea_pull_request_test.go	Add E2E coverage for skipped status reporting on Gitea/Forgejo.
test/bitbucket_datacenter_push_test.go	Update CreateCRD call signature to include opts/settings.
test/bitbucket_datacenter_pull_request_test.go	Add Bitbucket DC PR E2E coverage for skipped statuses + CreateCRD signature update.
test/bitbucket_datacenter_dynamic_variables_test.go	Update CreateCRD call signature to include opts/settings.
test/bitbucket_cloud_pullrequest_test.go	Add Bitbucket Cloud PR E2E coverage for skipped statuses.
pkg/provider/github/status.go	Map skipped conclusion appropriately for check runs and commit statuses; avoid empty DetailsURL in check run creation.
pkg/provider/github/status_test.go	Add unit coverage for skipped conclusion behavior (apps + webhook).
pkg/provider/gitea/status_test.go	Add unit coverage for skipped conclusion mapping (success + “Skipped” description).
pkg/provider/gitea/gitea.go	Add skipped conclusion formatting + map skipped to success for commit statuses.
pkg/provider/bitbucketdatacenter/bitbucketdatacenter.go	Map skipped conclusion to Bitbucket DC “UNKNOWN” state and update title text.
pkg/provider/bitbucketdatacenter/bitbucketdatacenter_test.go	Add unit coverage for skipped conclusion.
pkg/provider/bitbucketcloud/bitbucket.go	Update skipped title text for Bitbucket Cloud status reporting.
pkg/provider/bitbucketcloud/bitbucket_test.go	Add unit coverage for skipped conclusion.
pkg/pipelineascode/testdata/no-match/.tekton/nomatch.yaml	Add annotations to ensure deterministic “no-match” behavior for tests.
pkg/pipelineascode/pipelineascode.go	Report per-unmatched statuses (when enabled) after starting matched PipelineRuns; add helper reporter.
pkg/pipelineascode/pipelineascode_test.go	Add Run() test covering per-unmatched status reporting.
pkg/pipelineascode/pipelineascode_statuscheck_test.go	New unit tests for status reporting helper behavior and error emission.
pkg/pipelineascode/match.go	Plumb unmatched PipelineRuns through the matching flow.
pkg/pipelineascode/match_test.go	Update tests to validate unmatched PipelineRuns counts.
pkg/matcher/annotation_matcher.go	Return unmatched PipelineRuns alongside matches and populate unmatched list on non-match branches.
pkg/matcher/annotation_matcher_test.go	Add tests verifying unmatched PipelineRun tracking and related logs.
pkg/apis/pipelinesascode/v1alpha1/zz_generated.deepcopy.go	Regenerate deep-copies to include StatusCheck.
pkg/apis/pipelinesascode/v1alpha1/types.go	Add StatusCheck API types/constants and inheritance via Settings.Merge.
pkg/apis/pipelinesascode/v1alpha1/types_test.go	Add tests verifying StatusCheck inheritance/precedence.
docs/content/docs/operations/global-repository-settings.md	Link global settings doc to the new Status Check guide.
docs/content/docs/guides/statuses.md	Document the unmatched-PipelineRun status-check feature at a high level.
docs/content/docs/guides/repository-crd/status-check.md	New tech preview guide documenting configuration and provider behavior.
docs/content/docs/guides/_index.md	Update guide index card subtitle to mention status checks.
docs/content/docs/api/settings.md	Add API reference documentation for settings.status_check.
docs/content/docs/api/repository.md	Include status_check snippet in Repository API docs.
docs/content/docs/api/repository-spec.md	Include status_check snippet in RepositorySpec API docs.
config/300-repositories.yaml	CRD schema updates for the new spec.settings.status_check fields.

Files not reviewed (1)

• pkg/apis/pipelinesascode/v1alpha1/zz_generated.deepcopy.go: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[zakisk]

/retest