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 #

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

Run #

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)

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 #

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 #

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 #

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:

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