# Watch a run

Follow a run's jobs, steps and logs while it runs, and read why it failed or has not started.

Replace repo-id with the repository's id, run-id with the run's id and
job-id with a job's id.

## Prerequisites

- `ci:ListRuns` on the repository (`rn:ews::<organization id>:ci:repository/<repository id>`) to
  list its runs, and `ci:GetRun` on it to open one.
- `ci:GetRunLogs` on the repository to read logs. It is marked sensitive: build output can carry
  whatever a step printed, so the read-only policies do not include it, and a refused read is
  recorded in the audit log.
- In the console, also `git:GetRepository` on the repository; without it, and without
  `ci:ListRuns` or `ci:GetRun`, the repository's **CI** tab or the run page is not found. The
  organization-wide **Runs** page needs `ci:ListRuns` on all of CI (`rn:ews::<organization id>:ci:*`)
  and shows an access-denied notice without it.

## Open a run

**Console**
1. Open the repository, then open its **CI** tab. (Or open **Runs** under CI, which lists the runs
   of every repository with **Status** and **Trigger** filters.)
2. Open the run.

The page lists the run's **Jobs** on the left; the job that failed, or else the one running, is
selected. For the selected job it shows each step with its kind, exit code and duration, then the
job's log, grouped by step. While the run is live the page refreshes every few seconds and the log
follows new lines as long as you are scrolled to its end. Without `ci:GetRunLogs` the log reads
"Logs are not visible to you".

**CLI**
```sh
dcloud ci runs list repo-id
dcloud ci runs get run-id
dcloud ci jobs logs job-id --limit 1000
```

**API**
```http
GET /ci/api/repositories/repo-id/runs
```

```http
GET /ci/api/runs/run-id
```

```http
GET /ci/api/jobs/job-id/logs?limit=1000
```

## Result

- The run list holds the repository's 50 newest runs, newest first; there is no paging or filter
  in the API.
- A run comes with its `jobs` and the `steps` of every job, each with its status and times.
- A log page holds up to `limit` lines (500 when you leave it out, at most 1,000), and stops early
  at 2 MiB of text. Each line has its step, its stream (`stdout` or `stderr`) and its time. Pass
  the answer's `nextCursor` back as `cursor` for the next page; while a job runs, an empty page
  means no new lines yet. An altered cursor answers `400` "cursor: Invalid cursor".

## Why a run has not started

A queued run carries a `waiting` sentence that says why: in the console as a banner on the run and
as the tooltip of its status, in the API as the run's `waiting` field. A run waiting for a free
slot links to **See what is running**.

## Why a run failed

A failed run shows its error as a banner. When the error names a secret, the banner offers the
fix: **Grant _NAME_ to CI** for a secret that exists, **Create _NAME_** for one that does not. A
job that never started says "Not started: …", and a job whose machine went away says "The runner
stopped before this job finished". See [Troubleshooting](troubleshooting.md).

## Related

- [Cancel or re-run a run](cancel-or-rerun-a-run.md)
- [Download an artifact](download-an-artifact.md)
- `ci.runs.get` · `ci.jobs.logs`
