Merge pull request #47 from quarkus-qe/feature/document-gh-pr-comment

Document JBang script used to transform Flaky Run reports into a GitHub comment

README.md

@@ -36,4 +36,29 @@ Following script arguments are supported:
 | new-summary-report-path      | Jenkins job or GitHub action build number          | ./flaky-summary-report.json |
 
 Please note that all script arguments are optional.
-The JBang script requires new flaky report to exist, as the whole point of the script is to add new report to a summary.
+The JBang script requires new flaky report to exist, as the whole point of the script is to add new report to a summary.
+
+## Generate GitHub PR comment content
+You may want to transform a Flaky Run report into a GitHub comment.
+There is a JBang script that can be used to generate content of the comment:
+
+```bash
+jbang trust add https://github.com/raw/quarkus-qe/flaky-run-reporter
+jbang https://github.com/raw/quarkus-qe/flaky-run-reporter/main/jbang-scripts/GitHubPrCommentator.java overview-file=overview-file-name flaky-reports-file-prefix=flaky-run-report
+```
+
+Following script arguments are required:
+
+| Argument name             | Argument description                                                                                                                                                                                                                                   |
+|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| overview-file             | Overview file should contain list of jobs with flakes. Example content: `'PR - Linux - JVM build - Latest Version', 'PR - Linux - Native build - Latest Version', 'PR - Windows - JVM build - Latest Version'`.                                        |
+| flaky-reports-file-prefix | This scrip can create one comment from many Flaky Run reports. This argument specifies common prefix of all report files. Last 3 words of the Flaky Run report file are matched with the jobs from overview above. Checkout code and test for details. |
+
+Following environment variables are required:
+
+| Environment variable name | Environment variable description                                                                                                                              |
+|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| GH_REPO                   | GitHub project repository name. Expected format is `organization/project-name`, for example: `quarkus-qe/quarkus-test-framework`                              |
+| WORKFLOW_ID               | GitHub action URL has a workflow id in the URL, current format is: `https://github.com/organization-name/project-name/actions/runs/workflow-id?pr=pr-number`. |
+
+Funnily enough, this script expects PR number will be present in the file called `pr-number` placed in a directory where this script is executed.