Document caveat for PR event-related pipeline values

* Reorganizing content

* Documenting workaround for caveat

* Moving workaround

* Moving workaround...for real

* Making it a NOTE

* Clarifying

* Addressing linting error

Author: yaningo

docs/guides/modules/orchestrate/pages/github-trigger-event-options.adoc

@@ -91,12 +91,55 @@ a| * `opened`
 
 All pipelines triggered by link:https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request[pull request events] also have the following xref:reference:ROOT:variables.adoc#pipeline-values[pipeline values] populated:
 
-* `pipeline.event.github.pull_request.base.ref`: the name of the *base* (or target) branch of the PR - that is the branch that will receive the changes.
-* `pipeline.event.github.pull_request.head.ref`: the name of the *head* branch of the PR - that is the branch containing the changes to be merged.
-* `pipeline.event.github.pull_request.draft`: a boolean value indicating whether the pull request is a draft.
-+
-**Example**: To trigger a pipeline on `PR opened or pushed to, default branch and tag pushes`, and ensure that it never runs if the event is associated with a draft PR, use the following:
-+
+[NOTE]
+====
+If your config contains a logical statement referencing any of the pipeline values listed below, you must do one of the following to prevent the pipeline creation from failing:
+
+* Ensure your triggers only allow pull request related events.
+* Include a condition to ensure that the pipeline only runs for pull request related events: `pipeline.event.name == "pull_request"`.
+====
+
+[cols=".^1,1"]
+|===
+|Pipeline value |Description
+
+|`pipeline.event.github.pull_request.base.ref`
+|The name of the *base* (or target) branch of the PR - that is the branch that will receive the changes.
+
+|`pipeline.event.github.pull_request.head.ref`
+|The name of the *head* branch of the PR - that is the branch containing the changes to be merged.
+
+|`pipeline.event.github.pull_request.draft`
+|A boolean value indicating whether the pull request is a draft.
+
+|`pipeline.event.github.pull_request.title`
+|The title of the pull request.
+
+|`pipeline.event.github.pull_request.number`
+|The numeric identifier of the pull request.
+
+|`pipeline.event.github.pull_request.merged`
+|A boolean that indicates whether the PR was merged or not.
+|===
+
+These values are extracted directly from the GitHub event payload. The part after prefix `pipeline.event.github.*` matches the corresponding field in the pull request event structure described in link:https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request[the GitHub docs].
+
+**Examples**:
+
+If the trigger option is `PR opened or pushed to, default branch and tag pushes`, include the additional condition `pipeline.event.name == "pull_request"` to prevent the pipeline creation from failing on a `push` event:
+
+[,yaml]
+----
+workflows:
+  say-hello-workflow:
+    when: pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.number == 23
+    jobs:
+      - say-hello
+----
+
+
+To trigger a pipeline on `PR opened or pushed to, default branch and tag pushes`, and ensure that it never runs if the event is associated with a draft PR, use the following:
+
 [,yaml]
 ----
 workflows:
@@ -105,17 +148,10 @@ workflows:
     jobs:
       - myjob
 ----
-+
-** The condition `pipeline.event.github.pull_request.draft == false` excludes draft PRs from triggering the workflow.
-** `pipeline.event.name == "api"` ensures that the workflow runs when triggered manually via the web app or API.
-** `pipeline.event.name == "push"` ensures that the workflow runs when triggered via push to the default branch.
 
-
-* `pipeline.event.github.pull_request.title`: the title of the pull request.
-* `pipeline.event.github.pull_request.number`: the numeric identifier of the pull request.
-* `pipeline.event.github.pull_request.merged`: a boolean that indicates whether the PR was merged or not.
-
-These values are extracted directly from the GitHub event payload. The part after prefix `pipeline.event.github.*` matches the corresponding field in the pull request event structure described in link:https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request[the GitHub docs].
+* `pipeline.event.github.pull_request.draft == false` excludes draft PRs from triggering the workflow.
+* `pipeline.event.name == "api"` ensures that the workflow runs when triggered manually via the web app or API.
+* `pipeline.event.name == "push"` ensures that the workflow runs when triggered via push to the default branch.
 
 Config orchestration tools are available from within your pipelines are as follows: