Fast repository checkouts with Git snapshots

Git snapshots prepare a repository and working tree once, package them as a snapshot, and reuse that snapshot across ephemeral runners. A runner downloads and extracts the snapshot instead of fetching Git history and checking out every file itself.

This is most useful for large repositories where checkout time is a significant part of each job. Snapshots are keyed by the resolved commit, so repeated checkouts of the same commit reuse the same immutable snapshot.

Git snapshots currently support GitHub repositories on Namespace Linux and macOS runners. To use Git snapshots, configure a GitHub association so that Namespace has read-only access to the target organization and repositories.

CLI example

Pass a repository without a URL scheme, optionally followed by @ and a branch, tag, or commit. On Linux or macOS, run:

$
"$NSC_POWERTOYS_DIR/nsgit" snapshot clone "github.com/acme/project@main" ./project

The destination argument is optional and defaults to the repository name. If specified, it must not exist or must be an empty directory. You do not need to create the destination or start the snapshot service separately.

For reproducible CI checkouts, use the commit SHA rather than a moving branch or tag.

Include additional refs

By default, the snapshot contains the requested ref. If a job also needs another ref locally—for example, to compare a feature branch with main—include it with --additional_ref:

$
"$NSC_POWERTOYS_DIR/nsgit" snapshot clone --additional_ref main "github.com/acme/project@feature/my-change" ./project

The additional ref is included in the local Git data without changing the checked-out ref. Repeat --additional_ref to include more than one ref.

GitHub Actions example

Run nsgit instead of actions/checkout on a Namespace runner:

jobs:
  test:
    runs-on: nscloud-ubuntu-26.04-amd64-8x16
    steps:
      - name: Check out repository
        run: |
          "$NSC_POWERTOYS_DIR/nsgit" snapshot clone \
            "github.com/$GITHUB_REPOSITORY@$GITHUB_SHA" \
            "$GITHUB_WORKSPACE"

      - name: Run tests
        run: go test ./...

The same checkout command works on Linux and macOS. To run the job on macOS, replace runs-on with your Namespace macOS runner profile.

The checkout step needs only the nsgit snapshot clone command. GitHub creates $GITHUB_WORKSPACE as an empty directory for a fresh job, which is a valid destination.

How it works

Whenever a ref is requested, Namespace generates a snapshot of the repository contents and serves it from an internal Namespace cache.

When multiple jobs request the same ref, as commonly happens in CI, the same snapshot is served to each job. This amortizes the checkout time across those jobs.

Snapshots are ephemeral and are removed automatically after some time.