Skip to main content

ci.summary

The ci.summary function appends Markdown to the job summary of the current run. Locally, it renders the Markdown as formatted text on stderr.

Usage​

ci.summary(markdown = "", template = "", data = None)

Arguments​

markdown

The Markdown to append, as a string. Each call adds to the summary rather than replacing it, so a script can build the summary in several steps. Required unless template is given, and it cannot be combined with template or data, even when it is an empty string.

template

(Optional) The name of a template file to render into the summary, instead of passing markdown. It is a file name under ci.templates.base_path, or an absolute path. There is no default template, so data always needs a template.

data

(Optional) A dict that becomes the template context. Keys are read in the template as .key. Passing data without template fails with an argument error that says template= is required.

Templates​

A script can keep the layout of a summary in a template file and pass only the values:

  • A call with template= renders that file, with data as the context. A call with only markdown appends the text as written.
  • There is no configured default template. The ci.summary.template key belongs to the summaries Atmos writes for commands, and scripts never read it.
  • The name is resolved against ci.templates.base_path. A relative base_path resolves against the Atmos base_path. When no file has exactly that name, the name with a .md suffix is tried.
  • Templates use Go template syntax with the same functions as the built-in plan templates. The data dict is the template context.
  • A key that the template reads but data does not contain fails the render and names the key, so a typo does not write <no value> into the summary.

See script report templates for the configuration.

Returns​

The return value is None.

Behavior​

  • On GitHub Actions, the text is appended to the job summary file that the runner provides. The summary appears on the run page.
  • Locally, the Markdown is rendered as terminal Markdown on stderr.
  • The text is masked before it leaves the process, so secrets that Atmos knows about do not reach the summary.
  • In CI the call is gated by ci.summary.enabled. When it is off, the call warns, renders locally, and the script continues. See gating.

Examples​

Report a short result​

ci.summary("## Deploy\n\nDeployed **api** to `prod` in 42 seconds.")

Build a table​

rows = ["| Stack | Result |", "| --- | --- |"]
for stack, result in {"dev": "ok", "prod": "ok"}.items():
    rows.append("| " + stack + " | " + result + " |")
ci.summary("\n".join(rows))

Render a summary from a template​

.atmos/ci/templates/deploy.md
## Deploy to {{ .stack }}

{{ .count }} services deployed.
{{ range .services }}
- {{ . }}
{{ end }}
ci.summary(template = "deploy.md", data = {"stack": "prod", "count": 2, "services": ["api", "web"]})

Errors​

  • A missing or non-string markdown fails with an argument error that names ci.summary.
  • Passing markdown together with template or data (an empty string counts), a data value that is not a dict, or data without template fails with an argument error.
  • A template that does not exist fails the script with an error that names the resolved path and the value of ci.templates.base_path. A template that reads a key missing from data, or that fails to render, fails the script.
  • A failure to write the summary fails the script. A gated-off call never fails.

Related​

  • ci describes the module and the shared behavior rules.
  • CI job summaries configures the native summaries that Atmos writes for commands.
  • ci.comment posts Markdown to the pull request instead.