# Running workflows

The same `ci` binary runs a workflow on your machine and on the runner. A
local `ci run deploy` deploys for real, behind the same gates; `--until` and
`--stub` are the ways to rehearse.

## Check

```sh
ci validate               # every workflow in the repo
ci validate deploy        # one, by name or path
```

## Run

```sh
ci run <workflow> [flags]
```

`<workflow>` is a name under `.tangled/workflows` or a file path. By default
the main checkout is your working copy, uncommitted changes included. At a
gate, `ci` prompts in the terminal; without a terminal (a script, an agent)
the run pauses instead.

| Flag | Meaning |
|---|---|
| `--clean` | Run a fresh checkout of a commit, as the runner does |
| `--rev REV` | With `--clean`: the revision (a jj revset or git rev; default `@` or `HEAD`) |
| `--until ACTION` | Stop before this action runs: run `plan` without deploying |
| `--stub ACTION=FILE` | Use a result file instead of running the action, to test routing (repeatable) |
| `--repo NAME=PATH` | Use a local directory for an extra repo instead of a clean clone (repeatable) |
| `--detach` | Pause at gates instead of prompting; continue with `ci resume` |
| `--shell bash` | Run commands with plain bash, without devenv. For debugging only |
| `--ref REF` | Ref to report as `CI_REF`/`TANGLED_REF`, e.g. `refs/heads/main` |
| `--report` | Report the run to the appview (automatic for `audited` actions) |
| `--local-locks` | Take concurrency groups locally instead of from the runner |
| `--max-transitions N` | Loop guard (default 50) |
| `-q` | Don't print events (they are still recorded) |

```sh
ci run deploy --until deploy                                  # plan only
ci run deploy --stub health-check=fixtures/unhealthy.json     # walk the rollback path
ci run ci --clean --rev @-                                    # the parent commit, cleanly
```

## Run one action

```sh
ci action <workflow> <action> [--no-follow]   # start at an action; --no-follow runs only it
ci action --run <run> <action>                # a manual action against an earlier run
```

The second form runs a `manual: true` action as a child run with the earlier
run's checkouts and `$CI_STATE`, as the appview's buttons do.

## Answer a gate

```sh
ci resume <run|last>                 # prompt again
ci resume last --choose rollback     # by action name or option number
ci resume last --choose 1 --answer-file code.txt   # for an action with input
ci resume last --dismiss             # end the run
ci resume last --expire              # expire a gate past its deadline
```

`ci resume` takes `--detach`, `--shell`, `--report`, `--local-locks` and `-q`
like `ci run`.

## Look at runs

```sh
ci runs                  # local runs, oldest first
ci view <run|last>       # print a run's events; -f follows it
ci gc [--keep 168h] [-n] # delete finished runs older than --keep, compact mirrors
```

`ci gc` never deletes running or paused runs; `-n` only lists what it would
delete.

## On the runner

With `CI_APPVIEW_URL` and `CI_TOKEN` set:

```sh
ci trigger [--ref main] <repo> [workflow]                   # start a manual run
ci wait [--workflow w] [--timeout 1h] [--tail 60] <repo> [sha-prefix]   # wait and print its log
```

## Exit codes

`ci run`, `ci action`, `ci resume` and `ci view` exit with the run's status:

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Failure |
| 2 | Usage error |
| 3 | Cancelled |
| 75 | Waiting at a gate |