GitHub Actions checkout missing "lfs: true" in CI

By Kaveh Alemi·Latchkey

actions/checkout defaults to lfs: false, so it clones the repo with LFS pointers but does not download the objects. Any step that reads a tracked binary then sees pointer text instead of content.

What this error means

A workflow builds cleanly locally but fails in CI when a binary asset is unreadable, and the file contents show an LFS pointer rather than the real data.

# a step reads a model file that is actually a pointer
$ file assets/model.bin
assets/model.bin: ASCII text
$ head -1 assets/model.bin
version https://git-lfs.github.com/spec/v1

Common causes

The checkout step omits lfs: true

Without the input, actions/checkout skips the LFS fetch entirely, leaving pointers in the working tree.

A cached checkout config without LFS

Copied workflows often keep the default checkout, so LFS is silently never fetched in that job.

How to fix it

Add lfs: true to the checkout

1. Set lfs: true on the actions/checkout step in each job that needs binaries.
2. Optionally cache .git/lfs to speed up repeat runs.
3. Re-run and confirm the assets are real content.

- uses: actions/checkout@v4
  with:
    lfs: true

Pull LFS after checkout if you cannot change the step

When the checkout is shared, add a follow-up git lfs pull to materialize objects.

- run: git lfs pull

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

How to prevent it

• Standardize lfs: true in workflow templates that use LFS.
• Cache .git/lfs to keep the fetch cheap.
• Assert a known binary is not pointer text as an early CI check.

Frequently asked questions

Related guides

References

• Git reference manual
• GitHub Actions documentation