This error occurs when your CI/CD pipeline tries to checkout or clone a repository that uses Git LFS, but the CI runner lacks git-lfs. Configure your checkout action or install git-lfs in your pipeline script to resolve it.
Git LFS (Large File Storage) is an extension that stores large binary files outside the main Git repository while keeping lightweight pointer files in the repo. When a CI/CD pipeline checks out a repository that uses Git LFS, the runner must have git-lfs installed to download the actual file contents. The "git-lfs not installed in CI environment" error occurs when: 1. The CI runner image doesn't include git-lfs by default 2. The checkout action or clone command doesn't have LFS support enabled 3. Git LFS was not installed as a build step before the checkout 4. The pipeline uses a minimal Docker image without git-lfs This error commonly appears as: - `git-lfs filter-process: git-lfs: command not found` - `This repository is configured for Git LFS but 'git-lfs' was not found on your path` - `Skipping Git LFS files` - Build failures with missing binary files or corrupt file content
The most common fix for GitHub Actions is to enable LFS in the checkout action:
- uses: actions/checkout@v4
with:
lfs: trueThis tells the checkout action to install git-lfs and fetch LFS files automatically.
For large repositories with many LFS files, you can also fetch only specific files:
- uses: actions/checkout@v4
with:
lfs: true
# Optionally limit to specific paths
- run: |
git lfs pull --include="assets/*"GitLab CI has built-in LFS support. Enable it by ensuring GIT_LFS_SKIP_SMUDGE is not set or set to "0":
variables:
GIT_LFS_SKIP_SMUDGE: "0" # Download LFS files (default)
# Or explicitly fetch LFS files in your script
build:
script:
- git lfs install
- git lfs pull
- ./build.shTo skip LFS for faster checkout when you don't need binaries:
variables:
GIT_LFS_SKIP_SMUDGE: "1" # Skip LFS download for speedCircleCI images may not include git-lfs. Install it before checkout:
version: 2.1
jobs:
build:
docker:
- image: cimg/base:stable
steps:
- run:
name: Install Git LFS
command: |
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs
git lfs install
- checkout
- run:
name: Fetch LFS files
command: git lfs pullAlternative using the machine executor:
jobs:
build:
machine:
image: ubuntu-2204:current # Has git-lfs pre-installed
steps:
- checkout
- run: git lfs pullFor Jenkins, install git-lfs on the agent or add it to your pipeline:
pipeline {
agent any
stages {
stage('Setup') {
steps {
sh '''
# Install git-lfs if not present
if ! command -v git-lfs &> /dev/null; then
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install -y git-lfs
fi
git lfs install
'''
}
}
stage('Checkout') {
steps {
checkout scm
sh 'git lfs pull'
}
}
}
}For Docker-based Jenkins agents, ensure your Dockerfile includes git-lfs:
FROM jenkins/agent:latest
RUN apt-get update && apt-get install -y git-lfs && git lfs installAzure Pipelines checkout can be configured for LFS:
steps:
- checkout: self
lfs: true
fetchDepth: 0 # Full history for LFS references
# Or use the Git LFS task
- task: Bash@3
displayName: 'Install Git LFS'
inputs:
targetType: 'inline'
script: |
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs
git lfs install
git lfs pullFor Microsoft-hosted agents, git-lfs is typically pre-installed. Use lfs: true in checkout.
If your CI uses custom Docker images, add git-lfs to your Dockerfile:
Debian/Ubuntu-based:
FROM ubuntu:22.04
RUN apt-get update && \
apt-get install -y git curl && \
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | bash && \
apt-get install -y git-lfs && \
git lfs install && \
rm -rf /var/lib/apt/lists/*Alpine-based:
FROM alpine:3.18
RUN apk add --no-cache git git-lfs && \
git lfs installAmazon Linux / RHEL-based:
FROM amazonlinux:2023
RUN yum install -y git && \
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.rpm.sh | bash && \
yum install -y git-lfs && \
git lfs installTravis CI supports git-lfs configuration in .travis.yml:
git:
lfs_skip_smudge: false # Download LFS files (default)
# Or install manually for more control
before_install:
- git lfs install
- git lfs pullTo skip LFS for speed:
git:
lfs_skip_smudge: trueFor macOS builds:
os: osx
before_install:
- brew install git-lfs
- git lfs install
- git lfs pullFor self-hosted GitHub Actions runners, GitLab runners, or other self-managed CI infrastructure:
Install git-lfs on the runner machine:
# Ubuntu/Debian
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs
sudo git lfs install --system # System-wide installation
# macOS
brew install git-lfs
git lfs install
# Windows (run as Administrator)
winget install GitHub.GitLFS
git lfs installVerify installation:
git lfs version
git lfs envFor GitLab runners, ensure the runner's executor has git-lfs available. For Docker executors, use an image with git-lfs installed.
Add verification steps to your pipeline to confirm LFS is working:
# GitHub Actions example
- name: Verify Git LFS
run: |
echo "Git LFS version:"
git lfs version
echo "LFS-tracked files:"
git lfs ls-files
echo "LFS status:"
git lfs status
# Verify a specific LFS file exists and isn't a pointer
if head -c 100 path/to/large-file.bin | grep -q "^version https://git-lfs"; then
echo "ERROR: LFS file contains pointer, not actual content"
exit 1
fi
echo "LFS files downloaded successfully"This ensures your build won't proceed with broken LFS content.
### Caching LFS Files in CI
LFS downloads can be slow. Cache them to speed up builds:
GitHub Actions:
- name: Cache LFS files
uses: actions/cache@v4
with:
path: .git/lfs
key: lfs-${{ hashFiles('.gitattributes') }}
restore-keys: lfs-
- uses: actions/checkout@v4
with:
lfs: trueGitLab CI:
cache:
key: lfs-cache
paths:
- .git/lfs
build:
script:
- git lfs pull### Partial Clone to Skip LFS Entirely
If you don't need LFS files in CI (e.g., for linting or tests that don't use binaries):
# GitHub Actions
- uses: actions/checkout@v4
with:
lfs: false # Skip LFS entirely
# Set environment to prevent warnings
- run: git config lfs.fetchexclude "*"### Troubleshooting LFS in Docker Builds
When building Docker images that need LFS files:
# Bad: LFS files won't be real content
COPY . /app
# Good: Ensure LFS is pulled before build
# In your CI, run: git lfs pull
# Then build the Docker imageOr use multi-stage builds with LFS:
FROM alpine:3.18 AS lfs-fetch
RUN apk add --no-cache git git-lfs
WORKDIR /repo
COPY .git .git
COPY .gitattributes .
RUN git lfs install && git lfs pull
FROM node:20-alpine
COPY --from=lfs-fetch /repo /app### LFS Bandwidth and Rate Limits
CI/CD pipelines can exhaust LFS bandwidth quotas. Monitor usage:
- GitHub: Check Settings > Billing > Git LFS data
- GitLab: Check Group/Project Settings > Usage Quotas
- Bitbucket: Check Workspace Settings > Plan details
Consider using git lfs fetch --recent to only download recently updated LFS files.
### Alternative: Store Large Files Elsewhere
For very large files or high-bandwidth CI scenarios, consider:
- Storing binaries in artifact storage (S3, GCS, Azure Blob)
- Using a separate CDN for large test fixtures
- Mounting shared NFS/EFS volumes in CI runners
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server
fatal: unable to access: Proxy auto-configuration failed
How to fix 'Proxy auto-configuration failed' in Git
fatal: unable to access: Authentication failed (proxy requires basic auth)
How to fix 'Authentication failed (proxy requires basic auth)' in Git
fatal: unable to access: no_proxy configuration not working
How to fix 'no_proxy configuration not working' in Git
fatal: unable to read tree object in treeless clone
How to fix 'unable to read tree object in treeless clone' in Git