> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reliable Git checkouts in CI

> Make Git checkouts on Orka VMs and MacStadium Macs faster and more resilient: shallow and partial clones, stall timeouts for HTTPS and SSH, and caching repositories close to your builds.

Cloning repositories is often the first thing a CI job does, and the slowest. A large clone, or one that stalls partway, can hold up an otherwise quick build. These practices make checkouts on Orka VMs and MacStadium Macs faster, and keep a single slow connection from failing a build.

## Download less

If a build doesn't need the full history, a shallow or partial clone transfers far less data.

* A **shallow clone** fetches only the latest commit:

  ```bash theme={null}
  git clone --depth 1 <REPO_URL>
  ```

* A **partial clone** fetches the full history but downloads file contents only when a checkout needs them:

  ```bash theme={null}
  git clone --filter=blob:none <REPO_URL>
  ```

In GitHub Actions, `actions/checkout` already makes a shallow clone by default (`fetch-depth: 1`). Only raise it if a step needs history, such as one that compares against another branch.

## Abort stalled transfers so they retry

A transfer that slows to a crawl rarely recovers, but a new connection usually runs at full speed. Instead of waiting for a stalled clone, abort it and try again. How you do that depends on whether you clone over HTTPS or SSH.

### HTTPS clones

Git can abort an HTTPS transfer that stays below a minimum speed. For example, this aborts a transfer that stays under about 200 KB/s for 60 seconds:

```bash theme={null}
git config --global http.lowSpeedLimit 200000
git config --global http.lowSpeedTime 60
```

`http.lowSpeedLimit` is in bytes per second. Set it below the speed your normal clones reach, so a slow but healthy clone isn't cut off.

### SSH clones

The `http.lowSpeedLimit` and `http.lowSpeedTime` settings don't apply to SSH clones. Limit how long the clone can take instead:

* **Use your CI tool's timeout and retry.** For example, `timeout-minutes` on a GitHub Actions step, `timeout_in_minutes` with `retry: automatic` in Buildkite, or `timeout` with `retry` in GitLab CI.

* **Or wrap the clone in a timeout yourself.** macOS doesn't include a `timeout` command. Install Homebrew's `coreutils` and use `gtimeout`:

  ```bash theme={null}
  brew install coreutils
  gtimeout 300 git clone <REPO_URL>
  ```

* **Or clone over HTTPS,** so the low-speed settings apply.

### Retry the clone

Pair the timeout with a retry, so an aborted clone starts again instead of failing the build:

```bash theme={null}
for attempt in 1 2 3; do
  git clone --depth 1 <REPO_URL> <DIRECTORY> && break
  rm -rf <DIRECTORY>
  sleep 10
done
```

## Keep repositories close to your builds

The fastest clone is the one that doesn't reach the internet.

* **Seed the repository in your VM image.** Clone your largest repositories into the image you build for your Orka VMs. Each job then runs `git fetch` for recent changes instead of a full clone. Push a new version of the image now and then, so the fetches stay small. See [Save Orka VM changes to a local or OCI image](https://docs.macstadium.com/orka/oci-images/oci-images-preserve-changes.md).
* **Run a mirror next to your builds.** A Git mirror or cache server on the same network as your Orka nodes serves most fetches locally and only goes to your Git host for new commits. For build caching beyond Git, see [Bazel remote build execution with Orka](https://docs.macstadium.com/orka/orka-devops-integrations/bazel-rbe.md).

## Related pages

* [Orka required URL rules for filtering](https://docs.macstadium.com/orka/orka-resources/orka-required-url-rules-for-filtering.md)
* [Image caching](https://docs.macstadium.com/orka/orka-resources/image-caching.md)


## Related topics

- [GitLab CI/CD runners on Orka macOS VMs](https://docs.macstadium.com/orka/orka-devops-integrations/gitlab.md)
- [Orka tools, CLI downloads, and CI/CD plugins](https://docs.macstadium.com/orka/orka-overview/tools-integrations.md)
- [Orka CI/CD integrations quick start guide](https://docs.macstadium.com/orka/quick-start-guides/cicd-integrations-quick-start.md)
- [Migrate NFS Orka images to OCI format with Harbor](https://docs.macstadium.com/orka/oci-images/orka-self-service-migrating-nfs-images-to-oci-with-harbor.md)
- [GitHub Actions integration for Orka](https://docs.macstadium.com/orka/orka-devops-integrations/github-actions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.