# Action environment

Every action gets the engine's own environment, without any `CI_*` or
`TANGLED_*` variables left over from an enclosing run, then the workflow's
`environment:`, then the variables below. They are the same locally and on
the runner. See [DESIGN.md](../DESIGN.md) §9 for the full contract.

## `CI_*`

| Variable | Contents |
|---|---|
| `CI` | `true` |
| `CI_RUN_ID` | The run's id |
| `CI_RUN_DIR` | The run's directory |
| `CI_WORKFLOW` | Workflow name |
| `CI_ACTION` | This action's name |
| `CI_ATTEMPT` | How many actions this run has executed, counting this one |
| `CI_RESULT` | Where this action writes its [result](results.md) |
| `CI_STATE` | A directory shared by every action of the run, and by manual child runs of it. `outputs.json` in it holds the merged `outputs` of results |
| `CI_ARTIFACTS` | Where attachments go |
| `CI_INPUTS` | A JSON file: the `inputs` of the option that routed here (`{}` if none) |
| `CI_ANSWER` | For an action with `input`: a private file with the text typed at the gate. Removed when the action ends |
| `CI_TRIGGER_RESULT` | The result file that routed here, if any, so a rollback can read what the health check found |
| `CI_PARENT_RUN` | For a manual child run: the run it belongs to |
| `CI_ROOT` | The main checkout |
| `CI_SHA`, `CI_REF`, `CI_REPO` | The commit, ref and repo name being run |
| `CI_HOST` | `local` or `runner`. Informational; recipes shouldn't branch on it |

Each `repos:` entry with `env:` also sets that variable to its checkout's path.

Keep anything that must outlive an action in `$CI_STATE` or `$CI_ARTIFACTS`:
on the runner each action has a private `/tmp`, and a run that waits at a gate
continues in a new process.

## `TANGLED_*`

The variables Tangled's spindle sets, so a recipe can read the same names
under either: `TANGLED_SHA`, `TANGLED_COMMIT_SHA`, `TANGLED_REF`,
`TANGLED_REF_NAME`, `TANGLED_REF_TYPE` (`branch` or `tag`),
`TANGLED_PIPELINE_ID`, `TANGLED_PIPELINE_KIND`, `TANGLED_REPO_NAME`,
`TANGLED_REPO_DID`, `TANGLED_REPO_KNOT` and `TANGLED_REPO_DEFAULT_BRANCH`.
Some are empty on a local run.

## Variables the engine reads

| Variable | Meaning |
|---|---|
| `CI_RUNS_DIR` | Where local runs live. Default `$XDG_STATE_HOME/ci/runs` or `~/.local/state/ci/runs` |
| `CI_CACHE_DIR` | Mirrors of extra repos. Default `$XDG_CACHE_HOME/ci` or `~/.cache/ci` |
| `CI_CLONE_URL` | Clone URL for `repos:` names, with `{repo}`: `git@host:{repo}` |
| `CI_APPVIEW_URL`, `CI_TOKEN` | The appview and an agent token, for reporting local runs, taking the runner's locks, `ci trigger` and `ci wait` |