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

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 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 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.

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. 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. 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. 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:

# .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 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.
• 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 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}