How to attach a markdown page to GitHub Actions workflow run summary?

Question

The GitHub Action "dotnet-tests-report" attaches a markdown page with test results to the Github Action workflow run summary. This is really nice. Once the workflow has finished, it becomes immediately clear what the results are. Clear in a visual way.

It is open source but the code is complicated so I still did not figure out how to do this.

What I want is this:

1. Run some command-line statement that generates a markdown file
2. Run some code that "publishes" this
3. Attach it to the summary in Github Actions
4. Be happy that everyone in my company can see the results attached to the workflow

Answer 1

It uses the GitHub API to create a check run.

POST https://api.github.com/repos/{owner}/{repo}/check-runs

When creating or updating a checkrun, you can specify the output paramter in the request body. The action dotnet-tests-report use the text property of the output parameter for the report:

Properties of the output object	Description
title (string)	Required. The title of the check run.
summary (string)	Required. The summary of the check run. This parameter supports Markdown.
text (string)	The details of the check run. This parameter supports Markdown.
annotations (array of objects)	Adds information from your analysis to specific lines of code. Annotations are visible on GitHub in the Checks and Files changed tab of the pull request. The Checks API limits the number of annotations to a maximum of 50 per API request. To create more than 50 annotations, you have to make multiple requests to the Update a check run endpoint. Each time you update the check run, annotations are appended to the list of annotations that already exist for the check run. For details about how you can view annotations on GitHub, see "About status checks". See the annotations object description for details about how to use this parameter.
images (array of objects)	Adds images to the output displayed in the GitHub pull request UI. See the images object description for details.

See the code of the action: https://github.com/zyborg/dotnet-tests-report/blob/237826dc017f02ebf61377af95d1a12f8409a527/action.ps1#L133-L149

$url = "https://api.github.com/repos/$repoFullName/check-runs"
$hdr = @{
    Accept = 'application/vnd.github.antiope-preview+json'
    Authorization = "token $ghToken"
}
$bdy = @{
    name       = $report_name
    head_sha   = $ref
    status     = 'completed'
    conclusion = $conclusion
    output     = @{
        title   = $report_title
        summary = "This run completed at ``$([datetime]::Now)``"
        text    = $reportData
    }
}
Invoke-WebRequest -Headers $hdr $url -Method Post -Body ($bdy | ConvertTo-Json)

Answer 2

While looking for a similar solution I found there is an action available now: https://github.com/LouisBrunner/checks-action,

It actually saves you from crafting the request, and allows even to supply markdown file, like the following:

- name: Create CheckRun for code Coverage
      uses: LouisBrunner/[email protected]
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        name: Code Coverage
        conclusion: ${{ job.status }}
        output: "{\"summary\":\"Code Coverage\"}"
        output_text_description_file: coveragereport/Summary.md

Answer 3

The May 2022 post "Supercharging GitHub Actions with Job Summaries" from Konrad Pabjan does mention:

Actions users have been asking for this type of functionality for a long time.
User-generated content from Actions has previously been limited to logs and annotations. It can be difficult to aggregate and group lots of information.

Annotations are important when it comes to highlighting things, like errors and warnings, and are not suited for rich output, like test summaries or build reports.

To get around these issues, we’ve even seen users manually create check runs using our API using the GITHUB_TOKEN that is provided as part of a run, which leads to decreased productivity.

(That is what riQQ's answer describes, which is not optimal)

It’s clear that there’s been a feature gap, forcing users to improvise with less than ideal solutions, which is why we’ve developed Job Summaries!

So:

GitHub Actions Job Summaries allow for custom Markdown content on the run summary generated by each job.

Custom Markdown content can be used for a variety of creative purposes, such as:

• Aggregating and displaying test results
• Generating reports
• Custom output independent of logs

Create summaries

Simply output Markdown content to a new environment variable we’ve introduced called $GITHUB_STEP_SUMMARY.
Any Markdown content added to this file will then be displayed on the Actions run summary page.
That’s it!

steps:
  - name: Adding markdown
    run: echo ‘### Hello world! :rocket:’ >> $GITHUB_STEP_SUMMARY

Or, running tests as part of CI: