# CI runs on Lorx

What a push runs, how jobs reach runners, and how to follow, cancel and rerun runs.

## What a push runs

When you push a branch that has workflows in `.lorx/actions/`, Lorx plans a run from the files as they are in the pushed commit:
- it keeps only the jobs whose `paths` the push changed, on the branches they allow;
- it queues the jobs with nothing to wait for;
- it queues the rest as what they need passes.

A job whose `needs` failed is not run.

A queued job waits for a [runner](/docs/ci/runners) that can take it. If no runner is online, jobs wait in the queue. A job whose runner stops answering goes back in the queue for another, up to three attempts.

## Start, cancel and rerun runs

These are API calls today (see [API](/docs/api/overview)), made with a token that can write runs:

| | Call |
|---|---|
| Start a run by hand | `POST /api/v1/repos/{owner}/{repo}/runs` with `{ "ref": "main" }` |
| List runs | `GET /api/v1/repos/{owner}/{repo}/runs` (filter with `?status=`, `?branch=`, `?commit=`; older pages with `?before=` from `next_before`) |
| One run, with its jobs | `GET /api/v1/repos/{owner}/{repo}/runs/{number}` |
| A job's log | `GET /api/v1/repos/{owner}/{repo}/runs/{number}/jobs/{job}/log` |
| Cancel | `POST /api/v1/repos/{owner}/{repo}/runs/{number}/cancel` |
| Rerun | `POST /api/v1/repos/{owner}/{repo}/runs/{number}/rerun` |

For example, to see how the run for your last commit went:

```sh
curl -s -H "Authorization: Bearer $LORX_TOKEN" \
  "https://git.lorx.space/api/v1/repos/you/app/runs?commit=$(git rev-parse HEAD)"
```

A run's status is one of `queued`, `running`, `passed`, `failed`, `cancelled` or `error` (a workflow that doesn't parse). Each job says which runner ran it (`ran_on`).

Cancelling a run stops its running steps within a heartbeat (15 seconds).