# Delivery modes

Each repository has a delivery mode that decides when a fix is written and
pushed.

| Mode            | What happens with a fixable finding                                                                                         |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `ask` (default) | Upseam asks first, in Slack or with a checkbox in the dashboard issue. The patch is written, gated and pushed only after approval. |
| `auto`          | Upseam writes the patch, runs the gates, pushes `upseam/<group>` and opens the pull request right away.                     |

The installation has a default mode for its repositories, and each repository
can override it. New installations start with `ask`. Change either on the
settings page.

## Who can change the mode

You sign in to the settings page with GitHub. A repository's mode can be
changed by someone with admin access to that repository. Installation
settings, including the default mode, the model and Slack, can be changed by
someone with admin access to every repository of the installation. Others see
the page with its forms switched off.

## Approving a finding

Before a model is connected, findings are listed as ready to fix and not yet
offered for approval; see [Without a model](models.md#without-a-model). In the `ask` mode a finding waits in two places:

- **Slack**: a message with **Open PR**, **Snooze 7 days** and **Ignore**.
  After **Open PR**, Upseam writes the patch, pushes the branch, opens the
  pull request and updates the message with the pull request and its CI
  result.
- **Dashboard issue**: a checkbox under **Waiting for approval**. Ticking it
  does the same as **Open PR**, but only when the person who ticks it has
  write access to the repository.

Slack buttons do not check GitHub access: any full member of the connected
workspace can press them (see [Slack](slack.md#who-can-press-the-buttons)).
**Snooze 7 days** hides the finding for a week; **Ignore** switches it off for
good. Both are available only in Slack, not in the dashboard issue.

You approve the finding, not the code. The patch still passes the same gates
after approval, and code review happens in the pull request. If the group
changes before you press the button, the approval does not carry over.

## Always `ask`

Two kinds of pull requests wait for approval even in the `auto` mode:

- **Successor model** pull requests, because a new model may take different
  parameters and behave differently, and CI rarely calls the live API.
- **Dependabot and Renovate bumps.** Upseam's pull request carries the bot's
  commits, including the new SDK and its install scripts. GitHub runs
  Dependabot's own workflows with a read-only token and without secrets, but
  a pull request opened by Upseam runs your workflows with your secrets. That
  should happen only after a person decides.

## Why `ask` is the default

Upseam never runs your code or the model's answer. Your CI does: a branch
`upseam/*` in your repository triggers `push` and `pull_request` workflows
with your repository's secrets before anyone reviews the pull request. The
[patch gates](security.md#patch-gates) narrow what a patch can do, but a patch
that passes them can still change how data flows within two lines of the
matched code. In `ask`, nothing is pushed until a person approves the finding.

If you switch to `auto`, do this first:

- Keep secrets away from jobs that run on `upseam/*` branches before review,
  for example with a condition on `github.head_ref` or an environment with a
  required reviewer.
- Protect your default branch.