# Git Checkout Acceleration

Avrea can prepare a workflow's Git repository from a datacenter-local mirror
while its runner starts. The normal `actions/checkout` step remains in your
workflow and remains authoritative, but it can reuse the prepared repository
instead of downloading the same Git objects from GitHub.

Git checkout acceleration supports Linux and macOS runners and is off by
default.

## Enabling

Turn on **Git Checkout Acceleration** at the organization or repository level
in the [Avrea console](https://console.avrea.com), or use the CLI:

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

No workflow change is required for the root repository:

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

Enabling the setting creates and maintains an Avrea Git mirror. A new mirror
may need an initial synchronization, so the first workflow can still fetch
from GitHub while later workflows use the local mirror.

## Root precheckout and fallback

Avrea prepares the repository before the GitHub job starts. If precheckout
fails, the workflow falls back to the regular `actions/checkout` path and
fetches the repository directly from GitHub.

## Submodules

Submodule precheckout is a separate setting. It prepares authorized Git
objects, but it does not change the workflow's requested checkout behavior.
Keep using the `submodules` input on `actions/checkout`.

| Mode | Prepared repositories | `actions/checkout` input |
|---|---|---|
| `none` | Root repository only | Any value |
| `top-level` | Root and eligible direct submodules | `submodules: true` or `recursive` |
| `recursive` | Root and eligible nested submodules | `submodules: recursive` |

Select a mode in the console, or use the CLI:

```bash
avr settings set cache.git-submodules.mode top-level
```

For direct submodules:

```yaml title="workflow.yml"
- uses: actions/checkout@v7
  with:
    submodules: true
```

For nested submodules:

```bash
avr settings set cache.git-submodules.mode recursive
```

```yaml title="workflow.yml"
- uses: actions/checkout@v7
  with:
    submodules: recursive
```

Avrea discovers submodules from the root repository's pinned commit and
authorizes each repository server-side. An eligible private submodule must be
covered by the same GitHub App installation and have a ready Avrea Git mirror.
When settings are applied at repository scope, enable Git Checkout Acceleration
for both the root and each private submodule repository that should be
preloaded. Ineligible or unavailable submodules remain ordinary GitHub checkout
traffic.

Recursive discovery is bounded for runner startup safety. Submodules beyond
the supported depth or repository count are fetched normally by
`actions/checkout`.

## Git LFS

Git checkout acceleration prepares Git objects but does not download Git LFS
payloads. Enable the separate [Git LFS Cache](/cache/git-lfs/) and keep using
`lfs: true` when the workflow needs LFS files:

```yaml title="workflow.yml"
- uses: actions/checkout@v7
  with:
    lfs: true
    submodules: recursive
```

The Git LFS cache continues to use GitHub for authorization and caches only the
resulting object downloads.

## Current limitations

- Only GitHub repositories are eligible for Avrea Git mirrors.
- Windows runners use the normal GitHub checkout path.
- Additional repositories selected dynamically by later checkout steps are not
  root-preloaded.
- Submodule precheckout accelerates only server-authorized, ready mirrors.