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:
Follow me on GitHub:
Vincent A Cicirello
View My Detailed GitHub Activity
If you want to generate the equivalent to the above for your own GitHub profile, check out the cicirello/user-statistician GitHub Action.
Or visit my website:
Top comments (0)
Some comments have been hidden by the post's author - find out more