---
title: "GITHUB_STEP_SUMMARY: Write a GitHub Actions Job Summary"
description: "How GITHUB_STEP_SUMMARY works: append Markdown, the 1 MiB and 20-step limits, why the summary goes missing on failed runs, and a runnable workflow that turns JUnit XML into a test summary."
url: https://mergify.com/learn/github-actions/job-summary
---

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](https://mergify.com/about), Co-founder & CEO of MergifyUpdated October 30, 2026

## 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

<table class="w-full text-sm"><tbody class="divide-y divide-gray-300 bg-white text-gray-800"><tr><td class="px-4 py-3 align-top font-semibold text-dark whitespace-nowrap">One file per step</td><td class="px-4 py-3 align-top">Each step gets its own GITHUB_STEP_SUMMARY file. Summaries are isolated between steps, so broken Markdown in one step does not break the next.</td></tr><tr><td class="px-4 py-3 align-top font-semibold text-dark whitespace-nowrap">Append with &gt;&gt;, replace with &gt;</td><td class="px-4 py-3 align-top">Every &gt;&gt; adds to the step's summary (with a newline). A &gt; in Bash overwrites what that step wrote so far. Deleting the file removes the step's summary.</td></tr><tr><td class="px-4 py-3 align-top font-semibold text-dark whitespace-nowrap">1 MiB per step</td><td class="px-4 py-3 align-top">A step over the limit has its summary upload fail, with an error annotation.</td></tr><tr><td class="px-4 py-3 align-top font-semibold text-dark whitespace-nowrap">20 step summaries per job</td><td class="px-4 py-3 align-top">GitHub displays at most 20 step summaries for a job. Put several sections in one step if you have more.</td></tr><tr><td class="px-4 py-3 align-top font-semibold text-dark whitespace-nowrap">Secrets are masked</td><td class="px-4 py-3 align-top">A secret that ends up in the summary is masked, the same as in the log.</td></tr></tbody></table>

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](https://mergify.com/learn/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](https://mergify.com/product/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](https://mergify.com/learn/test-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: October 30, 2026

## 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.

[Get started](https://dashboard.mergify.com/)[See how Test Engine works](https://mergify.com/product/test-engine)
