Skip to main content

ci.output

The ci.output function sets a named output that later steps and jobs can read. Locally, it prints the pair on stderr, or appends it to a file when you set one.

Usage​

ci.output(name, value)

Arguments​

name
Required. The name of the output, as a string.
value

Required. The value, as a string. Multiline values are supported. Convert other types with str() or json.encode() first.

Returns​

The return value is None.

Behavior​

  • On GitHub Actions, the pair is written to the step output file. A multiline value is written in a form that keeps its line breaks intact.
  • Locally, the pair prints as name=value on stderr, and a multiline value prints in the heredoc form that GitHub Actions reads. When ATMOS_CI_OUTPUT names a file, the pair is appended to that file instead. The variable is read each time the call runs, so a step's env: block can set it.
  • Values are written exactly as given, because later steps consume them. To keep a value out of logs, call ci.mask first. See masking.
  • In CI the call is gated by ci.output.enabled, which also gates ci.env and ci.path. When it is off, the call warns, renders locally, and the script continues.

Examples​

Publish a version​

version = exec.run(["git", "describe", "--tags", "--always"], output = "capture").stdout.strip()
ci.output("version", version)

A later step reads it as steps.<id>.outputs.version in a GitHub Actions workflow.

Publish structured data​

ci.output("stacks", json.encode(["dev", "staging", "prod"]))

Errors​

  • A missing argument or a non-string name or value fails with an argument error that names ci.output.
  • A failure to write the output fails the script. A gated-off call never fails.

Related​

  • ci describes the module and the shared behavior rules.
  • CI output variables configures the native outputs that Atmos writes for commands.
  • ci.env exports an environment variable instead.