# How Git LFS Works in actions/checkout: Technical Implementation and Configuration Guide

> Learn how Git LFS works in actions/checkout. Discover configuration steps and technical details for seamless LFS management in your CI/CD workflows.

- Repository: [GitHub Actions/checkout](https://github.com/actions/checkout)
- Tags: deep-dive
- Published: 2026-07-18

---

**To enable Git LFS in actions/checkout, set `lfs: true` in your workflow, which triggers `git lfs install --local` before fetching and `git lfs fetch origin <ref>` after the standard Git fetch, while automatically skipping LFS retrieval when sparse checkout is configured to avoid unnecessary network traffic.**

The `actions/checkout` action provides native **Git LFS** (Large File Storage) integration through a coordinated multi-phase TypeScript implementation. This system allows GitHub Actions workflows to automatically resolve binary assets without manual LFS commands, while respecting performance optimizations and network resilience patterns built into the action's architecture.

## Enabling Git LFS via the `lfs` Input

The workflow triggers LFS handling through the **`lfs`** input parameter, documented in [`README.md`](https://github.com/actions/checkout/blob/main/README.md) at lines 148–151, which defaults to `false`. When set to `true`, this value propagates into the **`IGitSourceSettings.lfs`** boolean flag defined in [`src/git-source-settings.ts`](https://github.com/actions/checkout/blob/main/src/git-source-settings.ts) at line 63. This flag serves as the central gatekeeper; all downstream LFS logic checks this setting before executing any LFS-related commands.

## The Three-Phase LFS Execution Flow

The implementation follows a strict sequence to ensure LFS objects are available before the job proceeds, as orchestrated in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts).

### Phase 1: Installing the LFS Extension

Before any fetch operations occur, the action verifies the `settings.lfs` flag. If enabled, it executes `git lfs install --local` via the **`git.lfsInstall()`** method at lines 69–73 of [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts). This command prepares the local repository to recognize LFS filters and smudge/clean filters, running once per checkout to configure the environment without modifying global Git settings.

### Phase 2: Fetching LFS Objects

After the standard `git fetch` resolves the commit or tag, the action explicitly invokes **`git.lfsFetch(ref)`** at lines 42–48 of [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts). This executes `git lfs fetch origin <ref>` to retrieve the actual binary content from the LFS server. The fetch operation respects the same retry logic as standard Git commands, using the internal `retryHelper.execute` wrapper for resilience against transient network failures.

### Phase 3: Sparse Checkout Interactions

When **sparse checkout** is configured, `actions/checkout` automatically defers LFS fetching during the initial setup. This optimization prevents downloading large binary files that fall outside the sparse checkout patterns, reducing unnecessary network overhead. In this scenario, LFS objects are fetched on-demand by Git when the files are actually materialized in the working directory.

## Low-Level Command Implementation

The LFS commands are implemented as thin wrappers around the Git CLI in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts). The **`lfsInstall()`** method at lines 95–97 and **`lfsFetch(ref)`** method at lines 86–92 both utilize the `GitCommandManager` class. These methods inherit the same authentication handling and retry mechanisms as standard Git operations, ensuring consistent behavior for LFS authentication using the same tokens or SSH keys configured for the repository.

## Workflow Configuration Example

To enable Git LFS in your GitHub Actions workflow, add the `lfs` input to the checkout step:

```yaml

# .github/workflows/example.yml

name: LFS demo
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout with LFS
        uses: actions/checkout@v7
        with:
          lfs: true               # Enable Git LFS handling

          fetch-depth: 0          # Optional: fetch full history

```

This configuration triggers the full LFS pipeline: installing the extension via `git lfs install --local`, fetching objects for the specific ref via `git lfs fetch origin <ref>`, and preparing the working directory with resolved binary files.

## Summary

- **Opt-in activation**: Set `lfs: true` to enable LFS handling via the `IGitSourceSettings` interface defined in [`src/git-source-settings.ts`](https://github.com/actions/checkout/blob/main/src/git-source-settings.ts) at line 63.
- **Two-stage process**: The action runs `git lfs install --local` before fetching (lines 69–73), then `git lfs fetch origin <ref>` after the standard Git fetch (lines 42–48) in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts).
- **Sparse checkout awareness**: LFS fetching is automatically skipped when sparse checkout is enabled to optimize network usage and avoid downloading files outside the sparse cone.
- **Retry resilience**: Both LFS commands use the same `retryHelper.execute` logic as standard Git commands for robust network handling.
- **CLI wrappers**: Low-level LFS operations are implemented in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) with methods `lfsInstall()` (lines 95–97) and `lfsFetch()` (lines 86–92).

## Frequently Asked Questions

### Does actions/checkout fetch Git LFS objects by default?

No. The **`lfs`** input defaults to `false` in the action configuration according to the source. You must explicitly set `lfs: true` in your workflow file to enable automatic fetching of LFS objects. Without this flag, the repository checkout will contain LFS pointer files instead of the actual binary content.

### Why are my LFS files not downloading when using sparse checkout?

When **sparse checkout** is configured, `actions/checkout` intentionally skips the `git lfs fetch` step during initialization. This design prevents downloading large files that are excluded from the sparse checkout cone. The LFS objects are retrieved on-demand by Git when the files are actually materialized in the working directory, conserving bandwidth for files you do not need.

### How does actions/checkout handle LFS authentication?

LFS authentication leverages the same credential management as standard Git operations. The **[`git-command-manager.ts`](https://github.com/actions/checkout/blob/main/git-command-manager.ts)** implementation uses the configured Git credentials and remote helpers established during the initial repository authentication, ensuring `git lfs fetch` operations use the same tokens or SSH keys provided to the checkout action.

### Can I control which LFS objects are fetched during checkout?

The current implementation fetches LFS objects for the specific ref being checked out using `git lfs fetch origin <ref>`, as seen in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts). While the action does not expose granular refspec control specifically for LFS, it respects the `fetch-depth` input, ensuring LFS objects are retrieved only for the commits being fetched rather than the entire repository history.