This post continues my series on tips for developing GitHub Actions. In this post, I explain how an Action can write to the workflow job summary, so that the users of your Action can find details of the Action formatted with markdown via the Actions tab. I start with a simple example of writing to the workflow job summary from a step of a workflow. I then explain my approach in writing to the workflow job summary from a GitHub Action implemented in Python.

Table of Contents:

• How to Write to Job Summary from a Workflow Step
• How to Write to Job Summary from a GitHub Action Implemented in Python
• Where You Can Find Me

How to Write to Job Summary from a Workflow Step

The GitHub Actions framework provides a straightforward way to write to the job summary of a workflow run, which includes support for formatting with Markdown. Specifically, within the GitHub Actions framework there is an environment variable $GITHUB_STEP_SUMMARY, which is a file that corresponds to the job summary. Simply append to that file whatever it is that you want to include in the summary for the workflow run.

Here is a minimal workflow file that does this. It is set up to run on workflow_dispatch events, which means that you can manually run it from the Actions tab of your repository. Simply insert the following into a file with the extension .yml within your .github/workflows directory. It has a single step that just writes some sample Markdown with a level 1 heading, a level 2 heading, and a "Hello GitHub" message.

name: summary

on:
  workflow_dispatch:

jobs:
  summarize:

    runs-on: ubuntu-latest

    steps:
    - name: Write to workflow job summary
      run: |
        SUMMARY=$'# Testing Job Summary\n## Second Level Heading\nHello GitHub'
        echo "$SUMMARY" >> $GITHUB_STEP_SUMMARY

Insert this into a file with the extension .yml within your .github/workflows directory. Then go to the Actions tab, find your workflow, and click the Run workflow button. After it runs, click on the run, and you'll find something that looks like the following:

The above is a screenshot of an actual run of this very workflow.

How to Write to Job Summary from a GitHub Action Implemented in Python

I maintain several GitHub Actions implemented in Python as container actions. One of these, jacoco-badge-generator, produces coverage badges from JaCoCo test coverage reports. Additionally, it outputs the test coverage percentages to the workflow job summary. This example is based upon the approach I use in jacoco-badge-generator.

First, I have a template string that I later use to format the job summary with Markdown:

markdownSummaryTemplate = """## JaCoCo Test Coverage Summary
* __Coverage:__ {0:.3%}
* __Branches:__ {1:.3%}
* __Generated by:__ jacoco-badge-generator
"""

Then, I have a function that formats and outputs the job summary. Make sure that you append to the environment file GITHUB_STEP_SUMMARY. The reason that I check that it exists is that this particular GitHub Action is also designed to be used as a CLI tool outside of GitHub Actions. When someone is using it in CLI mode, such as on their local system, that environment variable won't exist, and there also isn't anywhere to actually output this markdown anyway. You also need to import os first with import os.

def add_workflow_job_summary(cov, branches) :
    """Adds a job summary.

    Keyword arguments:
    cov - Coverage percentage
    branches - Branches coverage percentage
    """
    if "GITHUB_STEP_SUMMARY" in os.environ :
        with open(os.environ["GITHUB_STEP_SUMMARY"], "a") as f :
            print(markdownSummaryTemplate.format(cov, branches), file=f)

Here is a screenshot from an actual run of this Action from one of my other projects that uses it:

Where You Can Find Me

Follow me here on DEV:

Vincent A. CicirelloFollow

Researcher and educator in A.I., algorithms, evolutionary computation, machine learning, and swarm intelligence

Follow me on GitHub:

cicirello / cicirello

My GitHub Profile

Vincent A Cicirello

Sites where you can find me or my work
Web and social media
Software development
Publications

If you want to generate the equivalent to the above for your own GitHub profile, check out the cicirello/user-statistician GitHub Action.

View on GitHub

Or visit my website:

Vincent A. Cicirello - Professor of Computer Science

Vincent A. Cicirello - Professor of Computer Science at Stockton University - is a researcher in artificial intelligence, evolutionary computation, swarm intelligence, and computational intelligence, with a Ph.D. in Robotics from Carnegie Mellon University. He is an ACM Senior Member, IEEE Senior Member, AAAI Life Member, EAI Distinguished Member, and SIAM Member.

cicirello.org