Merge pull request #89178 from mramendi/RHDEVDOCS-6347

RHDEVDOCS 6347 PAC: on-path-changed, on-path-changed-ignore annotations

Author: stevsmit

modules/op-matching-pipeline-run-using-pipelines-as-code.adoc

@@ -49,6 +49,61 @@ annotations:
 * Globs with pattern matching such as `"refs/heads/\*"`
 * Tags such as `"refs/tags/1.\*"`
 
+
+[id="path-matching-pipeline-run-using-pipelines-as-code_{context}"]
+== Matching changes in paths to a pipeline run
+
+You can match a pipeline run to changes in a set of paths. {pac} starts the pipeline run when a pull request includes changes in any of the paths that you list.
+
+The `pass:[*]` wildcard denotes any file in the directory. The `pass:[**]` wildcard denotes any file in the directory or any subdirectories on any level under the directory.
+
+You can use the following example to match the `pipeline-pkg-or-cli` pipeline run when a pull request changes any files in the `pkg` directory, the `cli` directory, or any subdirectories under the `cli` directory.
+
+[source,yaml]
+----
+apiVersion: tekton.dev/v1
+kind: PipelineRun
+metadata:
+  name: pipeline-pkg-or-cli
+annotations:
+  pipelinesascode.tekton.dev/on-path-changed: "["pkg/*", "cli/**"]"
+# ...
+----
+
+[id="exclude-path-matching-pipeline-run-using-pipelines-as-code_{context}"]
+== Excluding changes in paths from matching a pipeline run
+
+You can configure a pipeline run to exclude matching if a pull request makes changes only to files in a specified set of paths. If the pipeline run matches an event but the pull request includes changes only to files in the paths that you list, {pac} does not start the pipeline run.
+
+You can use the following example to match the `pipeline-docs-not-generated` pipeline run when a pull request changes any files under the `docs` directory or its subdirectories, except when the changes apply only to the `docs/generated` directory or its subdirectories.
+
+[source,yaml]
+----
+apiVersion: tekton.dev/v1
+kind: PipelineRun
+metadata:
+  name: pipeline-docs-not-generated
+annotations:
+  pipelinesascode.tekton.dev/on-path-changed: "["docs/**"]"
+  pipelinesascode.tekton.dev/on-path-changed-ignore: "["docs/generated/**"]"
+# ...
+----
+
+You can use the following example to match the `pipeline-main-not-docs` pipeline run when a pull request targets the `main` branch, except when the changes apply only to the `docs` directory or its subdirectories.
+
+[source,yaml]
+----
+apiVersion: tekton.dev/v1
+kind: PipelineRun
+metadata:
+  name: pipeline-main-not-docs
+annotations:
+  pipelinesascode.tekton.dev/on-target-branch: "[main]"
+  pipelinesascode.tekton.dev/on-event: "[pull_request]"
+  pipelinesascode.tekton.dev/on-path-changed-ignore: "["docs/**"]"
+# ...
+----
+
 [id="label-matching-pipeline-run-using-pipelines-as-code_{context}"]
 == Matching a pull request label to a pipeline run