# 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

```python
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](/functions/automation/ci#fork-gate).
- Values are written exactly as given, because later steps consume them. Call [`ci.mask`](/functions/automation/ci.mask)
  first for a value that must not appear in logs. See [masking](/functions/automation/ci#masking).
- In CI the call is gated by [`ci.output.enabled`](/cli/configuration/ci/output), 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

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

### Export a masked token

```python
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`](/functions/automation/ci) describes the module and the shared behavior rules.
- [`ci.path`](/functions/automation/ci.path) adds a directory to `PATH`, and [`ci.output`](/functions/automation/ci.output) sets a step output.