How to Enable Git LFS Support in actions/checkout: Complete Implementation Guide

Set lfs: true in your workflow configuration to enable Git LFS support, which automatically installs the LFS client and fetches large files during the checkout process.

The actions/checkout action supports repositories that use Git Large File Storage (LFS) through an optional boolean input. When enabled, the action handles the complete LFS workflow—from client installation to object fetching—without requiring manual Git commands in your workflow.

How Git LFS Support Works Internally

The LFS implementation follows a clear pipeline through the action's TypeScript source code. Understanding this flow helps debug issues and optimize performance.

Input Parsing and Validation

The process begins in src/input-helper.ts, where the action reads the lfs input from your workflow and converts it to a boolean:

// src/input-helper.ts (lines 22-24)
result.lfs = (core.getInput('lfs') || 'false').toUpperCase() === 'TRUE'

This parses the string input and defaults to false if the parameter is omitted, ensuring backward compatibility for existing workflows.

Command Manager Initialization

The parsed flag propagates to src/git-source-provider.ts, which creates a specialized Git command manager that understands LFS operations:

// src/git-source-provider.ts (lines 73-80)
return await gitCommandManager.createCommandManager(
    settings.repositoryPath,
    settings.lfs,
    settings.sparseCheckout != null
)

The second parameter (settings.lfs) tells the manager to prepare for LFS operations.

LFS Client Installation and Fetching

After repository initialization, the provider conditionally installs the LFS client and fetches large files:

// src/git-source-provider.ts (lines 69-72)
if (settings.lfs) {
    await git.lfsInstall()
}

Then, during the fetch phase:

// src/git-source-provider.ts (lines 46-49)
if (settings.lfs && !settings.sparseCheckout) {
    await git.lfsFetch(checkoutInfo.startPoint || checkoutInfo.ref)
}

The lfsFetch method retrieves the actual large file objects from your LFS server, making them available in your working directory.

Error Handling for Missing Dependencies

If Git or the LFS component is not available on the runner, the action fails early with a clear error:

// src/git-source-provider.ts (lines 84-88)
if (settings.lfs) {
    throw err   // re-throw when LFS is requested but Git isn't present
}

This prevents workflows from proceeding with corrupted or incomplete file data.

Configuring Git LFS in Your Workflow

Enable LFS support by adding the lfs parameter to your checkout step:

# .github/workflows/build.yml

name: Build with LFS
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository with LFS
        uses: actions/checkout@v4
        with:
          lfs: true
          fetch-depth: 0

Key configuration points:

• Default behavior: The lfs input defaults to false as defined in action.yml
• Fetch depth: Use fetch-depth: 0 for full history or keep the default fetch-depth: 1 if you only need the latest LFS objects
• Runner requirements: The Git LFS client must be installed on the runner (pre-installed on GitHub-hosted runners)

Performance and Compatibility Considerations

The LFS implementation in actions/checkout differs from standard Git operations in several ways:

• Parallel fetching: LFS objects are fetched in parallel where possible, optimizing download times for repositories with multiple large files
• Sparse checkout limitation: When sparseCheckout is configured, the action skips the automatic lfsFetch call (lines 46-49), requiring manual LFS operations if needed
• Storage impact: Large files consume bandwidth and storage quotas on your LFS server with each fetch

Summary

• Enable LFS by setting lfs: true in your actions/checkout step configuration
• Automatic installation occurs via git.lfsInstall() in src/git-source-provider.ts
• Object fetching runs automatically via git.lfsFetch() for non-sparse checkouts
• Error handling prevents silent failures when Git LFS is unavailable on the runner
• Source files involved include src/input-helper.ts, src/git-source-provider.ts, and src/git-command-manager.ts

Frequently Asked Questions

What happens if Git LFS is not installed on the runner?

The action throws an error and fails immediately. According to the source code in src/git-source-provider.ts (lines 84-88), when settings.lfs is true but the Git command manager fails to initialize, the error is re-thrown to prevent the workflow from continuing with missing large files.

Does enabling LFS affect checkout performance?

Yes, enabling LFS adds network overhead because the action must fetch large file objects from your LFS server after the initial Git clone. The implementation attempts to optimize this by running git lfs fetch in parallel where possible, but repositories with many large files will see increased checkout times proportional to the total data size.

Can I use LFS with sparse checkout?

You can enable both features simultaneously, but the automatic LFS fetch is disabled when sparse checkout is active. As shown in lines 46-49 of src/git-source-provider.ts, the condition !settings.sparseCheckout prevents the automatic lfsFetch call. You must manually run git lfs fetch after the checkout step if you need large files within your sparse checkout patterns.

What is the default value for the lfs input?

The lfs input defaults to false as defined in the action.yml file. This means you must explicitly set lfs: true to enable Git LFS support; otherwise, the action skips all LFS-related operations and large files will remain as pointer files in your working directory.

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