RHDEVDOCS-6781: Added content trigerring PipelineRun on Git tags

Author: Dhruv-Soni11

modules/op-triggering-pipelinerun-on-git-tags-using-pipelines-as-code.adoc

@@ -0,0 +1,47 @@
+// This module is included in the following assembly:
+// * pac/managing-pipeline-runs-pac.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="op-triggering-`pipelinerun`-on-git-tags-using-pipelines-as-code_{context}"]
+= Triggering a `PipelineRun` on Git tags
+
+[role="_abstract"]
+
+When you create or reference a Git tag in a repository that is integrated with {pac}, you can trigger a `PipelineRun` that corresponds to the commit associated with that tag. This capability enables you to test or deploy tagged versions of your code, supporting release-based workflows and version control practices.
+
+{pac} resolves the Git tag to its corresponding commit SHA and runs the `PipelineRun` defined for that commit. You can initiate or manage such runs by commenting on the tagged commit using supported GitOps commands.
+
+Triggering `PipelineRun` on Git tags is supported for GitHub App, GitHub Webhook, and GitLab integrations. This functionality is not currently available for Gitea, Bitbucket Cloud, or Bitbucket Data Center.
+
+You can use GitOps comment commands to interact with `PipelineRun` associated with a Git tag. Each command applies to either all `PipelineRun` for the tag commit or to a specific `PipelineRun` name. For example, `/test tag:<tag>` retriggers all `PipelineRun` that match the tag commit, while `/test <`pipelinerun`-name> tag:<tag>` retriggers only the specified `PipelineRun`. Similarly, `/retest` and `/cancel` commands can be used with or without a specific `PipelineRun` name to rerun or cancel `PipelineRun` related to the tagged commit. These commands provide fine-grained control over `PipelineRun` triggered by tagged commits.
+
+A `PipelineRun` configured to respond to tag events typically includes annotations such as `pipelinesascode.tekton.dev/on-target-branch: "[refs/tags/*]"` and `pipelinesascode.tekton.dev/on-event: "[push]"`. These annotations ensure that tag creation events are recognized as push events and processed correctly. When a tag is created or referenced, {pac} treats it as a push event and uses the resolved commit SHA to run the associated `PipelineRun`. The same logic applies to subsequent GitOps commands added as comments on the tagged commit.
+
+Tag based triggering is particularly useful in continuous delivery scenarios where specific versions or releases are represented by tags. This method enables you to validate and promote release artifacts consistently without modifying the branch state.
+
+The following example shows a minimal `PipelineRun` configuration that triggers on tag events:
+
+[source,yaml]
+----
+apiVersion: tekton.dev/v1beta1
+kind: PipelineRun
+metadata:
+  name: pipelinerun-on-tag
+  annotations:
+    pipelinesascode.tekton.dev/on-target-branch: "[refs/tags/*]"
+    pipelinesascode.tekton.dev/on-event: "[push]"
+spec:
+  pipelineSpec:
+    tasks:
+      - name: tag-task
+        taskSpec:
+          steps:
+            - name: echo
+              image: registry.access.redhat.com/ubi9/ubi-micro
+              script: |
+                echo "tag: {{ git_tag }}"
+----
+
+To trigger this PipelineRun from GitHub, open your repository and navigate to the *Tags* view or the *Releases* section. Click the tag, for example `v1.0.0`, to view its associated commit. Add a comment on that commit using one of the supported commands such as `/test tag:v1.0.0` or `/cancel tag:v1.0.0`.
+
+Tag-based triggering is particularly useful in continuous delivery scenarios where specific versions or releases are represented by tags.

pac/managing-pipeline-runs-pac.adoc

@@ -10,6 +10,8 @@ include::modules/op-verifying-pipeline-run-pac.adoc[leveloffset=+1]
 
 include::modules/op-running-pipeline-run-using-pipelines-as-code.adoc[leveloffset=+1]
 
+include::modules/op-triggering-pipelinerun-on-git-tags-using-pipelines-as-code.adoc[leveloffset=+1]
+
 include::modules/op-restarting-or-canceling-pipeline-run-using-pipelines-as-code.adoc[leveloffset=+1]
 
 include::modules/op-monitoring-pipeline-run-status-using-pipelines-as-code.adoc[leveloffset=+1]