Merge pull request #325 from Martchus/clone-from-comments

Document usage of `openqa-clone-and-monitor-job-from-pr` for PR comments

openqa-clone-and-monitor-job-from-pr

@@ -7,8 +7,8 @@ openqa-clone-and-monitor-job-from-pr
 
 =head1 SYNOPSIS
 
-Clones and monitors openQA jobs mentioned in a PR description as CI action. This
-script is supposed to be used via the GitHub action defined in
+Clones and monitors openQA jobs mentioned in a PR description or PR comment as
+CI action. This script is supposed to be used via the GitHub action defined in
 C<actions/clone-job/action.yaml> like this:
 
 =begin text
@@ -39,11 +39,50 @@ By default it will clone the job on o3 into the "Development / GitHub" group. To
 use a different openQA instance and group, set the environment variables
 C<OPENQA_HOST> and C<OPENQA_SCHEDULE_GROUP_ID> accordingly.
 
+For jobs mentioned in PR comments one can use the same GitHub action like this:
+
+=begin text
+---
+name: Clone an openQA test mentioned in a PR comment
+on:
+  issue_comment:
+    types: [created, edited]
+env:
+  OPENQA_HOST: ${{ vars.OPENQA_URL }}
+  OPENQA_API_KEY: ${{ secrets.OPENQA_API_KEY }}
+  OPENQA_API_SECRET: ${{ secrets.OPENQA_API_SECRET }}
+  GH_PR_URL: ${{ github.event.issue.pull_request.url }}
+  GH_COMMENT_BODY: ${{ github.event.comment.body }}
+  GH_COMMENT_AUTHOR: ${{ github.event.comment.user.login }}
+  GH_COMMENT_URL: ${{ github.event.comment.html_url }}
+  RESTRICT_ORGA: os-autoinst
+  RESTRICT_TEAM: tests-maintainer
+
+jobs:
+  clone_mentioned_job:
+    runs-on: ubuntu-latest
+    if: "github.event.issue.pull_request && contains(github.event.comment.body, 'openqa: Clone ')"
+    env:
+      GITHUB_TOKEN: ${{ secrets.GH_TOKEN_FOR_ACTIONS }}
+    container:
+      image: registry.opensuse.org/devel/openqa/containers/tumbleweed:client
+    steps:
+      - name: Clone and monitor job mentioned in PR comment
+        uses: os-autoinst/scripts/actions/clone-job@master
+=end text
+
+So it works very similar to the usage for PR descriptions. The most important
+difference is that you have to supply a GitHub token manually that is able to
+use the statuses API on the relevant repository (`repo:status` permission). You
+probably also want to restrict the cloning to members of a team via the
+`RESTRICT_` variables as shown in this example so the token also needs access to
+that (`read:org` permission).
+
 For local testing you may also invoke the script manually. Have a look at the
 handling of environment variables at the beginning of the script code as you
-need to set certain additional environment variables, the
-`test/05-clone-and-monitor.t` can also clarify this script's behavior from user
-perspective.
+need to set certain additional environment variables. The test
+`test/05-clone-and-monitor.t` can also clarify the behavior of this script from
+user perspective.
 
 =back