# What runs on your machines

Which machine executes a run, what credentials it holds and for how long, what the runner software on your own machines does, and what happens when something fails.

## Where a run executes

| Machine             | Started by                                       | Lifetime                                                        |
| ------------------- | ------------------------------------------------ | --------------------------------------------------------------- |
| Hosted machine      | Deutsche Cloud, for the run; billed as job minutes  | One run; deleted when the run ends                              |
| Runner pool machine | Deutsche Cloud, as an instance of your organization | Jobs of one repository or trust class, until its paid hour ends |
| Your runner         | You                                              | As long as you run it                                           |

The workspace already holds the repository at the run's commit: there is no checkout or registry
login step in the native format.

## Credentials a run holds

A native-format run holds these:

| Credential                    | Allows                                             | Valid for |
| ----------------------------- | -------------------------------------------------- | --------- |
| Clone token                   | Reading this repository                            | 6 hours   |
| Registry login token          | What the run identity may do in the registry       | 12 hours  |
| Run token                     | Reporting this run's status and logs, nothing else | 6 hours   |
| Cache or artifact upload link | Writing one object                                 | 1 hour    |
| Artifact download link        | Reading one object                                 | 5 minutes |

The run identity is a service account of the repository, `ci-` and the first eight characters of
the repository's id. In the registry it may pull any image of your organization and push to the
repositories of the repository's own name and that name followed by `-`, `.` or `_` and more
(`my-app` publishes `my-app`, `my-app-api` and `my-app.worker`), creating them on first push. A
name that is itself the name of another repository of your organization belongs to that one:
when a repository `my-app-api` exists, `my-app` cannot publish `my-app-api`. It cannot delete
images. A run's token cannot report for another run.

Secrets are resolved before the job starts and handed to that job only; see
[Give a job a secret](give-a-job-a-secret.md).

## Caches

A cache entry belongs to the repository and to the scope of the run that wrote it:

| The run                  | Writes           | Restores from, in order                                    |
| ------------------------ | ---------------- | ---------------------------------------------------------- |
| A push or a manual start | Its own ref      | Its own ref, then the default branch                       |
| A pull request           | The pull request | The pull request, its target branch, the default branch    |
| A merge queue build      | The queue branch | The queue branch, the protected branch, the default branch |

A pull request or an unmerged branch can read the default branch's cache but never replace it.

## The Deutsche Cloud agent on a Mac

The agent reports to Deutsche Cloud every 30 seconds and asks for work every 5 seconds, every 15 after
three empty answers. While it executes a run it asks every 10 seconds whether the run was
cancelled. It runs as root through a launch daemon and downloads its program again at every start.
See [Connect a Mac](connect-a-mac.md).

## Runner pool machines

A pool machine proves itself with its instance identity token; no credential is stored on it. It
runs GitHub's runner, one job at a time. Between jobs every container, network and volume the job
left is removed and the work directory emptied; a job with an environment or an OIDC token is its
machine's last.

## When something fails

- **The Deutsche Cloud agent stops reporting** while it executes a run: after five minutes the run
  fails with "The runner build-mac-1 stopped reporting: no heartbeat for 5 minutes. Its jobs were
  stopped; start the runner again and re-run.", and its unfinished jobs read "The runner stopped
  before this job finished". The log ends where the machine stopped.
- **GitHub's runner stops reporting** while it runs a job (on your machine or a pool's): after ten
  minutes the job fails with "the runner stopped reporting (no lock renewal for 10 minutes)".
- **No runner with the labels is online**: the run fails after 20 minutes with
  `no online runner with label macos`.
- **A secret cannot be resolved**: the run fails before any job starts, naming the secret.
- **A run passes its time limit**: it ends `timed_out`.

## Related

- [Runners and runner groups](runners-and-groups.md)
- [Security in CI](security.md)
