# Git LFS Cache

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

Avrea can cache Git LFS objects in storage colocated with your runners. The
first checkout downloads an object from GitHub and fills the cache. Later
checkouts of the same repository can read that object locally, reducing both
checkout time and repeated GitHub downloads.

## Enabling

The Git LFS cache is **off by default**. Turn on **Git LFS Cache** at the
organization or repository level in the
[Avrea console](https://console.avrea.com), or enable it for a repository with
the CLI:

```bash
avr settings set cache.lfs.enabled true
```

Organization-level settings apply to all repositories by default, and a
repository-level setting overrides the organization value. See
[Managing Cache](/cache/managing/) for details.

Once enabled, no workflow changes are needed. Keep using Git LFS and
`actions/checkout` normally:

```yaml title="workflow.yml"
jobs:
  build:
    runs-on: avrea-ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          lfs: true
      - run: ./build.sh
```

## How it works

Git LFS still negotiates each transfer with GitHub, so GitHub continues to
authorize access to the repository. Avrea only caches the resulting object
download. Uploads from `git lfs push` pass through to GitHub and are not
cached.

Objects are cached per repository and are never shared across repository
boundaries. Git LFS entries count toward the repository's cache quota and
appear as the `lfs` cache type in cache usage and entry views. They follow the
same retention and eviction rules described in
[Storage & Eviction](/cache/storage/).

If the cache cannot serve a request, the download falls back to GitHub. Cache
availability does not block a checkout.

<Aside>
The cache currently covers Git LFS downloads from GitHub made by tools running
directly on an Avrea runner. Git LFS traffic originating inside a container is
not intercepted.
</Aside>