# Training requests

> The review unit — what goes into one, how it gets approved, and how it moves through its statuses.

::div{class="flex items-start gap-6"}
::div{class="shrink-0 flex items-center justify-center mt-1 size-24 rounded-4xl bg-dim-200"}
:u-icon{name="i-lucide-file-terminal" class="size-16 text-primary"}
::

A **training request** is a proposal to run training. It's the central object in TReqs, it's where the name TReqs comes from. It works the way a pull request does: you describe what you want to run, hand it off for review, document pre-run analysis, and execute when ready.
::

The reason for the review step is cost and accountability. A training run can occupy expensive hardware for hours or days. A training request makes the plan legible — the exact code, the exact stages, the exact machine — before anyone spends that.

## What a request is made of

A training request ties together four things:

- **Project** it belongs to, which supplies the repository.
- **Code**: a source branch and, ultimately, a full immutable commit.
- **Workflow file** at that commit, the worflow defines the stages or tasks. See [Workflows](/docs/workflows).
- **Compute target** it will run on. See [Compute targets](/docs/compute-targets).

When a request is queued it produces a **training run**, which is the hand-off for execution.

## Creating a TR

From the dashboard, open a project and choose **New training request**. From the CLI:

```bash [TReqs CLI]
treqs tr create --title "Baseline run"
treqs tr create --title "Train v2" --workflow-path .treqs/workflows/train.yaml
treqs tr create --title "GPU run" --compute-target gpu-box --status open
```

## Status flow

| Status | Meaning |
| --- | --- |
| **Draft** | (Optional) Being written. Not up for review, not runnable. |
| **Open** | Up for review, and — once approved — queueable. |
| **Done** | Finished. Its run completed. |
| **Cancelled** | Abandoned. Closed without completing. |

## Opening for review

Opening a request is what puts it in front of reviewers. It requires a compute target — you can't ask someone to approve a run without saying where it will run:

```bash [TReqs CLI]
treqs tr open <request-id> --compute-target gpu-box
treqs tr open <request-id> --compute-target gpu-box --reviewer alice
```

An open request needs **at least one assigned reviewer** before any approve or reject decision will be accepted. Assign them when you open it, or add them afterwards — `--reviewer` adds to whoever is already on the request, and can be repeated.

## Review

Each assigned reviewer holds one of three states:

| Review state | Meaning |
| --- | --- |
| **Pending** | Assigned, hasn't decided yet. |
| **Approved** | Happy for this to run. |
| **Changes Requested** | Not yet — something needs to change first. |

Reviewers decide from the request page, or from the CLI:

```bash [TReqs CLI]
treqs tr review approve <request-id>
treqs tr review reject <request-id> # ' = "Changes Requested"
treqs tr comment <request-id> --body "Can we pin the dataset version?"
```

Reviewers are notified when they're assigned and when a request they're reviewing changes. See [Notifications](/docs/notifications).

## Who can configure review controls

The admins allowed to configure training request controls for an organization's projects is itself a setting, under **Configure → Permissions**. 

There are two modes:

- **All Admins** — any admin or owner of the organization can configure TR controls.
- **Specific Admins** — only the admins you name.

## Queueing

Once a request is Open and approved, queue it:

```bash [TReqs CLI]
treqs tr queue <request-id>
```

That creates a job and prints its ID. From there, [Training runs](/docs/training-runs) takes over.