Skip to main content

ci.env

The ci.env function exports an environment variable to the steps that run after the current one. Locally, it prints an export line you can paste or source.

Usage​

ci.env(name, value)

Arguments​

name
Required. The name of the environment variable, as a string.
value
Required. The value, as a string. Multiline values are supported.

Returns​

The return value is None.

Behavior​

  • On GitHub Actions, the variable is written to the environment file that the runner reads between steps. It does not change the environment of the script that sets it.
  • Locally, the call prints export NAME=value on stderr, with the value shell-quoted only when it needs quoting. When ATMOS_CI_ENV names a file, the pair is appended to that file instead, in the NAME=value form that GitHub Actions reads. That form is unquoted on purpose.
  • Under pull_request_target and workflow_run, the call is held for a pull request from a fork, because writing the environment file there is a known injection vector. See the fork gate.
  • Values are written exactly as given, because later steps consume them. Call ci.mask first for a value that must not appear in logs. See masking.
  • In CI the call is gated by ci.output.enabled, which also gates ci.output and ci.path. When it is off, the call warns, renders locally, and the script continues.

Examples​

Export a region for later steps​

ci.env("AWS_REGION", "us-east-2")

Export a masked token​

token = exec.run(["gh", "auth", "token"], output = "capture").stdout.strip()
ci.mask(token)
ci.env("REGISTRY_TOKEN", token)

Errors​

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

Related​

  • ci describes the module and the shared behavior rules.
  • ci.path adds a directory to PATH, and ci.output sets a step output.