feat: add skip CI command support

Implement support for skip CI commands in commit messages to allow
users to skip PipelineRun execution. Supports [skip ci], [ci skip],
[skip tkn], and [tkn skip] commands.

When a skip command is detected in the commit message, PipelineRun
execution is skipped. However, GitOps commands (/test, /retest, etc.)
will still trigger PipelineRuns regardless of the skip command,
allowing users to manually trigger CI when needed.

Jira: https://issues.redhat.com/browse/SRVKP-8933

Signed-off-by: Akshay Pant <akshay.akshaypant@gmail.com>

Author: theakshaypant

README.md

@@ -65,6 +65,7 @@ Before getting started with Pipelines-as-Code, ensure you have:
 - **Multi-provider support**: Works with GitHub (via GitHub App & Webhook), GitLab, Gitea, Bitbucket Data Center & Cloud via webhooks.
 - **Annotation-driven workflows**: Target specific events, branches, or CEL expressions and gate untrusted PRs with `/ok-to-test` and `OWNERS`; see [Running the PipelineRun](https://pipelinesascode.com/docs/guide/running/).
 - **ChatOps style control**: `/test`, `/retest`, `/cancel`, and branch or tag selectors let you rerun or stop PipelineRuns from PR comments or commit messages; see [GitOps Commands](https://pipelinesascode.com/docs/guide/gitops_commands/).
+- **Skip CI support**: Use `[skip ci]`, `[ci skip]`, `[skip tkn]`, or `[tkn skip]` in commit messages to skip automatic PipelineRun execution for documentation updates or minor changes; GitOps commands can still override and trigger runs manually; see [Skip CI Commands](https://pipelinesascode.com/docs/guide/gitops_commands/#skip-ci-commands).
 - **Feedback**: GitHub Checks capture per-task timing, log snippets, and optional error annotations while redacting secrets; see [PipelineRun status](https://pipelinesascode.com/docs/guide/statuses/).
 - **Inline resolution**: The resolver bundles `.tekton/` resources, inlines remote tasks from Artifact Hub or Tekton Hub, and validates YAML before cluster submission; see [Resolver](https://pipelinesascode.com/docs/guide/resolver/).
 - **CLI**: `tkn pac` bootstraps installs, manages Repository CRDs, inspects logs, and resolves runs locally; see the [CLI guide](https://pipelinesascode.com/docs/guide/cli/).

docs/content/docs/guide/matchingevents.md

@@ -486,3 +486,97 @@ main and the branch called `release,nightly` you can do this:
 ```yaml
 pipelinesascode.tekton.dev/on-target-branch: [main, release,nightly]
 ```
+
+## Skip CI Commands
+
+Pipelines-as-Code supports skip commands in commit messages that allow you to skip
+PipelineRun execution for specific commits. This is useful when making documentation
+changes, minor fixes, or work-in-progress commits where running the full CI pipeline
+is unnecessary.
+
+### Supported Skip Commands
+
+You can include any of the following commands anywhere in your commit message to skip
+PipelineRun execution:
+
+* `[skip ci]` - Skip continuous integration
+* `[ci skip]` - Alternative format for skipping CI
+* `[skip tkn]` - Skip Tekton PipelineRuns
+* `[tkn skip]` - Alternative format for skipping Tekton
+
+**Note:** Skip commands are **case-sensitive** and must be in lowercase with brackets.
+
+### Example Usage
+
+```text
+docs: update README with installation instructions [skip ci]
+```
+
+or
+
+```text
+WIP: refactor authentication module
+
+This is still in progress and not ready for testing yet.
+
+[ci skip]
+```
+
+### How Skip Commands Work
+
+When a commit message contains a skip command:
+
+1. **Pull Requests**: No PipelineRuns will be created when the PR is opened or updated and HEAD commit contains skip command. A neutral status check will be displayed on the PR indicating that CI was skipped.
+2. **Push Events**: No PipelineRuns will be created when pushing to a branch with that commit message. A neutral status check will be displayed on the commit.
+
+**Note:** A neutral status check is created on your git provider to provide visibility that the commit was acknowledged but CI was intentionally skipped. This helps distinguish between commits that were ignored due to skip commands versus commits where CI hasn't run.
+
+### GitOps Commands Override Skip CI
+
+**Important:** Skip CI commands can be overridden by using GitOps commands. Even if
+a commit contains a skip command like `[skip ci]`, you can still manually trigger
+PipelineRuns using:
+
+* `/test` - Trigger all matching PipelineRuns
+* `/test <pipelinerun-name>` - Trigger a specific PipelineRun
+* `/retest` - Retrigger failed PipelineRuns
+* `/retest <pipelinerun-name>` - Retrigger a specific PipelineRun
+* `/ok-to-test` - Allow running CI for external contributors
+* `/custom-comment` - Trigger PipelineRun having on-comment annotation
+
+This allows you to skip automatic CI execution while still maintaining the ability
+to manually trigger builds when needed.
+
+### Example: Skipping CI Then Manually Triggering
+
+```bash
+# Initial commit with skip command
+git commit -m "docs: update contributing guide [skip ci]"
+git push origin my-feature-branch
+# No PipelineRuns are created automatically
+# A neutral status check is displayed on the commit/PR
+
+# Later, you can manually trigger CI by commenting on the PR:
+# /test
+# This will create PipelineRuns despite the [skip ci] command
+```
+
+### Examples of When to Use Skip Commands
+
+Skip commands are useful for:
+
+* Documentation-only changes
+* README updates
+* Comment or formatting changes
+* Work-in-progress commits
+* Minor typo fixes
+* Configuration file updates that don't affect code
+
+### Examples of When NOT to Use Skip Commands
+
+Avoid using skip commands for:
+
+* Code changes that affect functionality
+* Changes to CI/CD pipeline definitions
+* Dependency updates
+* Any changes that should be tested before merging

pkg/adapter/sinker.go

@@ -3,10 +3,12 @@ package adapter
 import (
 	"bytes"
 	"context"
+	"fmt"
 	"net/http"
 
 	"github.com/openshift-pipelines/pipelines-as-code/pkg/apis/pipelinesascode/v1alpha1"
 	"github.com/openshift-pipelines/pipelines-as-code/pkg/kubeinteraction"
+	"github.com/openshift-pipelines/pipelines-as-code/pkg/matcher"
 	"github.com/openshift-pipelines/pipelines-as-code/pkg/params"
 	"github.com/openshift-pipelines/pipelines-as-code/pkg/params/info"
 	"github.com/openshift-pipelines/pipelines-as-code/pkg/pipelineascode"
@@ -69,8 +71,98 @@ func (s *sinker) processEvent(ctx context.Context, request *http.Request) error
 		if err := s.processEventPayload(ctx, request); err != nil {
 			return err
 		}
+
+		// For ALL events: Setup authenticated client early (including token scoping)
+		// This centralizes client setup and token scoping in one place for all event types
+		repo, err := s.findMatchingRepository(ctx)
+		if err != nil {
+			// Continue with normal flow - repository matching will be handled in matchRepoPR
+			s.logger.Debugf("Could not find matching repository for early client setup: %v", err)
+		} else {
+			// We found the repository, now setup client with token scoping
+			// If setup fails here, it's a configuration error and we should fail fast
+			if err := s.setupClient(ctx, repo); err != nil {
+				return fmt.Errorf("client setup failed: %w", err)
+			}
+			s.logger.Debugf("Client setup completed early in sinker for event type: %s", s.event.EventType)
+		}
+
+		// For PUSH events: commit message is already in event.SHATitle from the webhook payload
+		// We can check immediately without any API calls or repository lookups
+		if s.event.EventType == "push" && provider.SkipCI(s.event.SHATitle) {
+			s.logger.Infof("CI skipped for push event: commit %s contains skip command in message", s.event.SHA)
+			return s.createSkipCIStatus(ctx)
+		}
+
+		// For PULL REQUEST events: commit message needs to be fetched via API
+		// Get commit info for skip-CI detection (only if we successfully set up client above)
+		if s.event.EventType == "pull_request" && repo != nil {
+			// Get commit info (including commit message) via API
+			if err := s.vcx.GetCommitInfo(ctx, s.event); err != nil {
+				return fmt.Errorf("could not get commit info: %w", err)
+			}
+			// Check for skip-ci commands in pull request events
+			if s.event.HasSkipCommand {
+				s.logger.Infof("CI skipped for pull request event: commit %s contains skip command in message", s.event.SHA)
+				return s.createSkipCIStatus(ctx)
+			}
+		}
 	}
 
 	p := pipelineascode.NewPacs(s.event, s.vcx, s.run, s.pacInfo, s.kint, s.logger, s.globalRepo)
 	return p.Run(ctx)
 }
+
+// findMatchingRepository finds the Repository CR that matches the event.
+// This is a lightweight lookup to get credentials for early skip-ci checks.
+// Uses the canonical matcher implementation to avoid code duplication.
+func (s *sinker) findMatchingRepository(ctx context.Context) (*v1alpha1.Repository, error) {
+	// Use canonical matcher to find repository (empty string searches all namespaces)
+	repo, err := matcher.MatchEventURLRepo(ctx, s.run, s.event, "")
+	if err != nil {
+		return nil, fmt.Errorf("failed to match repository: %w", err)
+	}
+	if repo == nil {
+		return nil, fmt.Errorf("no repository found matching URL: %s", s.event.URL)
+	}
+
+	return repo, nil
+}
+
+// setupClient sets up the authenticated client with token scoping for ALL event types.
+// This is the primary location where client setup and GitHub App token scoping happens.
+// Centralizing this here ensures consistent behavior across all events and enables early
+// optimizations like skip-CI detection before expensive processing.
+func (s *sinker) setupClient(ctx context.Context, repo *v1alpha1.Repository) error {
+	return pipelineascode.SetupAuthenticatedClient(
+		ctx,
+		s.vcx,
+		s.kint,
+		s.run,
+		s.event,
+		repo,
+		s.globalRepo,
+		s.pacInfo,
+		s.logger,
+	)
+}
+
+// createSkipCIStatus creates a neutral status check on the git provider when CI is skipped.
+func (s *sinker) createSkipCIStatus(ctx context.Context) error {
+	statusOpts := provider.StatusOpts{
+		Status:     "completed",
+		Conclusion: "neutral",
+		Title:      "CI Skipped",
+		Summary:    fmt.Sprintf("%s - CI has been skipped", s.pacInfo.ApplicationName),
+		Text:       "Commit contains a skip CI command. Use /test or /retest to manually trigger CI if needed.",
+		DetailsURL: s.run.Clients.ConsoleUI().URL(),
+	}
+
+	if err := s.vcx.CreateStatus(ctx, s.event, statusOpts); err != nil {
+		s.logger.Warnf("Failed to create skip-CI status: %v", err)
+		// Don't return error - skip-CI should succeed even if status creation fails
+		return nil
+	}
+
+	return nil
+}