Document how to schedule tests via @openqa: in a GHA

And mention that comments require API access.

See: https://progress.opensuse.org/issues/191635

Author: kalikiana

docs/WritingTests.asciidoc

@@ -2330,11 +2330,31 @@ feature is explained in further detail in the corresponding
 <<UsersGuide.asciidoc#scenarios_yaml,users guide section>>.
 
 It is also possible to create a GitHub workflow that will clone and monitor an
-openQA job which is mentioned in the PR description or comment. The scripts
-repository contains a pre-defined GitHub action for this. Checkout the
-documentation of the
-https://github.com/os-autoinst/os-autoinst-scripts/blob/master/openqa-clone-and-monitor-job-from-pr[openqa-clone-and-monitor-job-from-pr]
-script for further information and an example configuration.
+openQA job which is mentioned in the PR description using https://github.com/os-autoinst/os-autoinst-scripts/blob/master/openqa-clone-and-monitor-job-from-pr[openqa-clone-and-monitor-job-from-pr] with something like this:
+
+----
+name: Schedule openQA tests mentioned via @openqa:
+on:
+  pull_request_target:
+  workflow_dispatch:
+env:
+  OPENQA_HOST: ${{ secrets.OPENQA_URL }}
+  OPENQA_API_KEY: ${{ secrets.OPENQA_API_KEY }}
+  OPENQA_API_SECRET: ${{ secrets.OPENQA_API_SECRET }}
+  GH_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+  GH_REF: ${{ github.event.pull_request.head.ref }}
+  GH_PR_BODY: ${{ github.event.pull_request.body }}
+jobs:
+  clone_and_monitor_job_from_pr:
+    runs-on: ubuntu-latest
+    container:
+      image: registry.opensuse.org/devel/openqa/containers/tumbleweed:client
+    steps:
+      - uses: os-autoinst/os-autoinst-scripts/actions/clone-job@master
+----
+
+In this example the body of the PR is passed via `GH_PR_BODY`. Comments can also
+be provided but this requires use of the GitHub API via the comments endpoint.
 
 NOTE: These examples show how API credentials are supplied. It is important to
 note that using `on:pull_request` would only work for PRs created on the main
@@ -2343,14 +2363,6 @@ repository but not for PRs created from forks. Therefore
 version the variables under `github.event.pull_request.head.*` are utilized
 (instead of e.g. just `$GITHUB_REF`).
 
-NOTE: Due to the use of `on:pull_request_target` the scenario definitions are
-read from the main repository in this example. This is the conservative
-approach. To allow scheduling jobs based on the PR version of the scenario
-definitions file one could use e.g.
-`SCENARIO_DEFINITIONS_YAML_FILE=https://raw.githubusercontent.com/$GH_REPO/$GH_REF/.github/workflows/openqa.yml`
-instead of `- uses: actions/checkout@v3` and
-`--param-file SCENARIO_DEFINITIONS_YAML=scenario-definitions.yaml`.
-
 === Use webhooks and status reporting APIs of GitHub
 This approach is so far specific to GitHub and is a bit more effort to setup
 than the approach mentioned in the previous section. For this to work, GitHub