Overview
The built-in checkout step on CircleCI Docker (cimg/*) and machine executor images (e.g., ubuntu-2204, ubuntu-2004) does not automatically install or invoke Git LFS. As a result, repositories that track files with Git LFS will complete the checkout step successfully, but LFS-tracked files will contain pointer references instead of actual file content.
This behavior is intentional. Git LFS is an opt-in extension, and automatically pulling LFS objects on every build would add unnecessary time and bandwidth costs for the majority of jobs that do not use it.
Some older machine image versions did include git-lfs and handled LFS pulls automatically during checkout. Current images do not, which may cause unexpected behavior when upgrading image versions.
Solution
Machine Executor
Add a run step immediately after checkout to install git-lfs and pull LFS files:
jobs:
build:
machine:
image: ubuntu-2204:current
steps:
- checkout
- run:
name: Install git-lfs and pull LFS files
command: |
sudo apt-get update && sudo apt-get install -y git-lfs
git lfs install
git lfs pull
- run:
name: Verify LFS files
command: git lfs ls-filesDocker Executor (cimg/* Images)
For Docker executors, the installation method differs slightly since git-lfs is not available via the default apt repositories:
jobs:
build:
docker:
- image: cimg/base:current
steps:
- checkout
- run:
name: Install git-lfs and pull LFS files
command: |
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get update
sudo apt-get install -y git-lfs
git lfs install
git lfs pullSelective LFS Pulling
If only certain jobs need LFS files, set the GIT_LFS_SKIP_SMUDGE environment variable to prevent automatic smudging, then pull explicitly where needed:
jobs:
build-without-lfs:
machine:
image: ubuntu-2204:current
environment:
GIT_LFS_SKIP_SMUDGE: "1"
steps:
- checkout
# LFS files are not downloaded -- faster checkout build-with-lfs:
machine:
image: ubuntu-2204:current
steps:
- checkout
- run:
name: Install git-lfs and pull LFS files
command: |
sudo apt-get update && sudo apt-get install -y git-lfs
git lfs install
git lfs pull