# Persistent disks

import { Aside } from '@astrojs/starlight/components';

A persistent disk keeps files between jobs of one repository. Use it for
dependency stores, build outputs, toolchains, or anything else that is slow to
recreate and safe to rebuild.

Persistent disks are enabled per organization. If your repository settings do
not show **Persistent disk**, contact [support@avrea.com](mailto:support@avrea.com).
They are available only in datacenters with persistent storage.

Persistent disks are a paid feature: see [Pricing](#pricing).

## Enable a persistent disk

1. Open the repository's **Settings** in the
   [Avrea console](https://console.avrea.com).
2. Under **Persistent disk**, turn on the operating systems that should get a
   disk. Linux, macOS and Windows each get their own disk and filesystem.
3. Optionally set the size: 10 to 500 GB, 50 GB by default. Size can only
   grow; a larger size applies the next time a disk is attached.

Workflows find the disk through `$PERSISTENT_DISK_PATH`:

| Operating system | Path |
| --- | --- |
| Linux | `/mnt/persistent` |
| macOS | `/Volumes/AVREA_PERSISTENT` |
| Windows | `P:\` |

```yaml title="workflow.yml"
- name: Restore dependencies from the persistent disk
  run: |
    mkdir -p "$PERSISTENT_DISK_PATH/deps"
    ./scripts/install-deps --cache-dir "$PERSISTENT_DISK_PATH/deps"
```

Persistence is best effort. When storage is unavailable, the job runs without
the disk, so workflows should also work from an empty or missing disk.

## How branches share the disk

Each job gets its own copy of the disk. Whether its changes are kept depends
on the branch:

- **Writer branches publish.** By default only the repository's default branch
  (for example `main`) is a writer. When a writer job finishes, its copy
  becomes the new disk, so the most recently published default-branch run is
  what later jobs start from. Change the list under **Writer branches**; use
  exact branch names, and `$default` for the default branch.
- **Pull requests and other branches start from the published disk.** They
  receive a writable copy of the latest published contents. Their changes are
  discarded when the job ends and never reach the published disk or other
  jobs.
- **Concurrent writers do not merge.** Writer jobs that run at the same time
  start from the same published version. The first one to finish publishes;
  the others started from an older version, so their changes are discarded.
  An older copy never overwrites newer contents.
- **Only cleanly finished jobs publish.** A job whose steps failed still
  publishes if the runner finished normally. Cancelled and crashed jobs do not
  publish.

<Aside type="caution" title="Treat the disk as readable by any job">
Every job in the repository, including pull requests from forks, can read the
published disk. Store only content you can rebuild, and never store secrets
or credentials on it.
</Aside>

## Docker and Git caches

[Docker cache on persistent disk](/cache/build-cache/docker/#docker-cache-on-persistent-disk)
and **Git cache on persistent disk** store their data on the Linux disk and
follow the same branch rules. They do not add a separate storage charge.

## Reset or disable

- **Reset** erases one operating system's disk and provisions a fresh one.
  Jobs may wait for the replacement or run without the disk meanwhile.
- **Disable** permanently deletes every persistent disk of the repository, in
  all operating systems and datacenters, including Docker and Git caches.
  Re-enabling creates fresh, empty disks.

Disks that are in use must finish their current activity before a reset or
disable is accepted. Neither action can be undone.

## Pricing

Persistent disks cost **$0.50 per provisioned GB per month**, prorated for
partial months.

- Charges are for provisioned size, not used space. Idle disks are billed
  while they exist.
- Each operating system and datacenter disk is billed separately. One 50 GB
  disk costs $25 for a full month; Linux and macOS disks of 50 GB each cost
  $50.
- Charges start when a disk is ready and stop as soon as a disable is
  accepted. A reset pauses charges until the replacement is ready.
- Per-job copies are not billed separately.

Persistent-disk charges draw on the same monthly credit as runner minutes. See
[Billing](/billing/#free-monthly-minutes).