Skip to content
GitHub Actions

GITHUB_STEP_SUMMARY: write a GitHub Actions job summary

GitHub Actions gives every step a file called $GITHUB_STEP_SUMMARY. Write Markdown to it and it shows up, rendered, on the run's summary page. Here is how it behaves, the limits nobody reads until they hit them, and a short script that turns a JUnit report into a test summary.

By Julien Danjou, Co-founder & CEO of MergifyUpdated

In one paragraph

Append Markdown with echo "..." >> "$GITHUB_STEP_SUMMARY" and it renders under the job on the workflow run's summary page. Each step has its own file, capped at 1 MiB, and a job shows at most 20 of them. The step that writes a test summary needs if: ${{ !cancelled() }}, otherwise it is skipped on the runs where tests fail. A summary describes one run. It does not remember the previous one.

The one-line version

GITHUB_STEP_SUMMARY is an environment variable holding the path of a file. Anything you append to that file is read as GitHub-flavored Markdown when the step ends:

- name: Say hello
  run: echo "Tests ran on Python $(python --version | cut -d' ' -f2)" >> "$GITHUB_STEP_SUMMARY"

Open the run, click Summary, and the line sits under the job's name. Tables, headings, links, emoji, <details> blocks and code fences all render. It needs no action and no token.

How it behaves, and its limits

One file per stepEach step gets its own GITHUB_STEP_SUMMARY file. Summaries are isolated between steps, so broken Markdown in one step does not break the next.
Append with >>, replace with >Every >> adds to the step's summary (with a newline). A > in Bash overwrites what that step wrote so far. Deleting the file removes the step's summary.
1 MiB per stepA step over the limit has its summary upload fail, with an error annotation.
20 step summaries per jobGitHub displays at most 20 step summaries for a job. Put several sections in one step if you have more.
Secrets are maskedA secret that ends up in the summary is masked, the same as in the log.

From GitHub's workflow commands reference, as of October 2026.

A test summary from JUnit XML

The summary everyone wants is the test results: how many passed, and which ones failed with what message. Your test runner already writes them as JUnit XML, so a short script can read the file and print Markdown. This one needs nothing beyond Python's standard library, so it works whatever your tests are written in:

"""Print a Markdown test summary from a JUnit XML file."""

import sys
import xml.etree.ElementTree as ET

passed, skipped, failed = 0, 0, []
for case in ET.parse(sys.argv[1]).getroot().iter("testcase"):
    problem = case.find("failure")
    if problem is None:
        problem = case.find("error")
    if problem is not None:
        message = (problem.get("message") or "").splitlines()[0][:200]
        failed.append((f"{case.get('classname')}.{case.get('name')}", message))
    elif case.find("skipped") is not None:
        skipped += 1
    else:
        passed += 1

icon = "❌" if failed else "✅"
print(f"### {icon} {passed} passed, {len(failed)} failed, {skipped} skipped")
if failed:
    print()
    print("| Test | Message |")
    print("| --- | --- |")
    for name, message in failed:
        message = message.replace("|", "\\|")
        print(f"| `{name}` | {message} |")

Save it as .github/scripts/junit_summary.py and call it after the tests:

name: Tests

on:
  pull_request:

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: "3.13"
      - run: pip install -r requirements.txt
      - name: Run tests
        run: pytest --junitxml=junit.xml
      - name: Test summary
        if: ${{ !cancelled() }}
        run: python .github/scripts/junit_summary.py junit.xml | tee -a "$GITHUB_STEP_SUMMARY"

if: ${{ !cancelled() }} is the line that matters. Without it the summary step is skipped as soon as the test step fails, so you get a summary on every green run and none on the red ones. tee -a writes the same Markdown to the log too, which helps when you are reading the raw log of a run. On our first run the flaky test failed, and the summary read:

### ❌ 3 passed, 1 failed, 0 skipped

| Test | Message |
| --- | --- |
| `tests.test_calc.test_flaky` | assert 0.12023537803633866 > 0.4 |

If you would rather not maintain a script, the report actions write a job summary as well. GitHub Actions test report compares dorny/test-reporter, EnricoMi/publish-unit-test-result-action, mikepenz/action-junit-report and ctrf-io/github-test-reporter.

What a job summary forgets

The summary above is accurate and it is alone. The next run writes a new one with no idea the last run existed, so a test that fails on Monday and passes on Tuesday reads as a failure, then as nothing. Nobody re-reads old summaries to notice the pattern.

That pattern is what Mergify Test Engine keeps. It records every test's result from every run, classifies each test as healthy, flaky or broken from that history, and can quarantine the flaky ones so they keep running without failing the job. It does not write the job summary for you: keep this script, or your report action, for the run in front of you, and let Test Engine remember the runs behind it. For pytest it is the pytest-mergify plugin and a MERGIFY_TOKEN secret, next to the summary step above.

FAQ

What is GITHUB_STEP_SUMMARY?

An environment variable GitHub Actions sets in every step. It holds the path of a file; whatever Markdown the step writes to that file is rendered on the workflow run's summary page, under the job. No action, permission or token is needed.

Where does the job summary show up?

On the summary page of the workflow run, one section per job. It is not posted on the pull request; reviewers see it by opening the run from the pull request's checks.

Why is my job summary empty?

Usually because the step that writes it did not run. A step without an if: condition is skipped once an earlier step fails, which is exactly when a test summary matters. Give it an if: condition on !cancelled(). The other usual cause is writing with > in a later command of the same step, which replaces what the step wrote before.

Is there a size limit on the job summary?

Yes: 1 MiB per step. Over that, the step's summary upload fails with an error annotation. GitHub also displays at most 20 step summaries per job.

Can I write the job summary from JavaScript?

Yes. Actions written in JavaScript can use the summary helpers of @actions/core, which build Markdown and HTML and write them to the same file. In a plain run step, appending to $GITHUB_STEP_SUMMARY is all there is to it.

Does Mergify Test Engine write a job summary?

No. Test Engine keeps per-test history across runs, classifies tests as flaky or broken, and quarantines the flaky ones; the summary of a single run is still yours to write, with a script like the one on this page or a report action. Keep both.

Last updated:

A summary for this run, a memory for all of them

Keep your job summary. Add per-test history, flaky detection and quarantine to the same GitHub Actions workflow. Free for up to 5 users.