GitLab CI/CD Git LFS Large-File Pipeline Prompt

You are a senior DevOps engineer who runs GitLab CI pipelines against repositories that store large binaries in Git LFS — game assets, ML datasets, design files, firmware images. You know exactly how the GitLab Runner fetches LFS objects, where bandwidth and quota get burned, and how smudge/pointer confusion breaks jobs.

I will provide:
- Repo contents (what LFS tracks: `.gitattributes` patterns, rough object sizes/counts)
- Runner type (shared SaaS / self-hosted shell / Docker / Kubernetes executor)
- The failing or slow job and its `.gitlab-ci.yml` snippet
- Symptoms (pointer files instead of binaries, slow clones, quota exhausted, smudge errors)
- Goal (fix correctness / cut fetch time / cut bandwidth / add locking)

Your job:

1. **Diagnose smudge vs. pointer state**:
   - A 130-ish-byte file starting `version https://git-lfs.github.com/spec/v1` is an un-smudged pointer — LFS content was never fetched.
   - Confirm which jobs actually need real binaries vs. which only need source; only the former should smudge.
2. **Control what the runner fetches** with pipeline variables:
   - `GIT_LFS_SKIP_SMUDGE: "1"` skips automatic download at checkout (fast clone, pointers only).
   - Then `git lfs pull --include="path/**" --exclude=""` fetches only the paths a job needs.
   - `GIT_DEPTH` controls history depth; shallow clone still resolves LFS for the checked-out ref.
3. **Cache LFS objects across jobs/pipelines**:
   - Cache `.git/lfs/objects` keyed on the `.gitattributes` + lockfile hash so unchanged assets are reused.
   - Prefer fetch-once-in-`prepare`, expose as artifact or cache, and `GIT_LFS_SKIP_SMUDGE` everywhere else.
4. **Verify the runner has LFS installed**: the `gitlab-runner` helper image includes `git-lfs`; custom `image:` may not — add `git lfs install --skip-repo` in `before_script` when using your own image.
5. **Handle partial fetches for monorepos**: combine sparse-checkout with `--include` globs so a job pulls only its slice of LFS.
6. **Protect quota**: report expected bandwidth per pipeline (objects × size × job count) and recommend where to dedupe.
7. **Locking (if collaborative binaries)**: show `git lfs lock`/`unlock` usage and explain it is advisory, not a CI gate.

Deliverables:
- Corrected `.gitlab-ci.yml` with the right LFS variables per job
- The exact `git lfs` commands to fetch only what is needed
- A cache block keyed correctly for LFS reuse
- A bandwidth estimate and the single biggest reduction lever

Mark DESTRUCTIVE or RISKY: any `git lfs prune`/`git lfs migrate` on shared build dirs, global smudge-skip that could ship pointers to production, and force-push of migrated LFS history.

---

LFS tracked paths + sizes: [DESCRIBE]
Runner/executor: [shared / shell / docker / kubernetes]
Failing/slow job (YAML): [PASTE]
Symptoms: [pointers / slow / quota / smudge error]
Goal: [correctness / speed / bandwidth / locking]

Why this prompt works

Most Git LFS breakage in CI is not a bug — it is the runner doing exactly what it was told: smudging everything on every job, or skipping smudge and shipping pointer files. This prompt forces a per-job decision about who actually needs the binaries, which is where both the correctness and the speed wins live.

How to use it

1. Identify which jobs need real LFS content vs. pointers only.
2. Skip smudge globally, then git lfs pull --include per job.
3. Cache .git/lfs/objects so assets are fetched once.
4. Confirm your custom image actually ships git-lfs.

Useful commands

# Is this file a pointer or the real object?
git lfs pointer --check --file assets/model.bin
head -c 200 assets/model.bin        # pointer starts: version https://git-lfs...

# Fetch only what a job needs
export GIT_LFS_SKIP_SMUDGE=1
git lfs pull --include="assets/models/**" --exclude=""

# Show tracked patterns and local cache size
git lfs track
du -sh .git/lfs/objects

# Verify runner image has LFS
git lfs version || (apt-get update && apt-get install -y git-lfs)
git lfs install --skip-repo

GitLab CI patterns

Skip smudge globally, fetch per job

variables:
  GIT_LFS_SKIP_SMUDGE: "1"        # clone pulls pointers only — fast

test:
  image: node:20
  script:
    - npm ci
    - npm test                    # no binaries needed; pointers are fine

package-assets:
  image: node:20
  before_script:
    - git lfs install --skip-repo
    - git lfs pull --include="assets/**" --exclude=""   # only real binaries
  script:
    - ./scripts/bundle-assets.sh

Cache LFS objects across pipelines

package-assets:
  variables:
    GIT_LFS_SKIP_SMUDGE: "1"
  cache:
    key:
      files:
        - .gitattributes
    paths:
      - .git/lfs/objects
    policy: pull-push
  before_script:
    - git lfs install --skip-repo
    - git lfs pull --include="assets/**" --exclude=""
  script:
    - ./scripts/bundle-assets.sh

Fetch-once, share as artifact

lfs-fetch:
  stage: .pre
  variables:
    GIT_LFS_SKIP_SMUDGE: "1"
  script:
    - git lfs pull --include="firmware/**" --exclude=""
  artifacts:
    paths:
      - firmware/
    expire_in: 1 hour

build-image:
  stage: build
  needs: [lfs-fetch]              # reuses fetched binaries, no re-download
  script:
    - ./build.sh firmware/

Common findings this catches

• Jobs reading 130-byte pointer files because smudge was skipped but no lfs pull was added.
• Every job re-downloading the full LFS set, silently burning namespace bandwidth quota.
• A custom image: without git-lfs, so checkout leaves pointers with no error.
• No --include scoping, so a monorepo job pulls gigabytes it never touches.

When to escalate

• Repeated quota exhaustion — evaluate an S3-backed LFS object store or LFS-less large-file strategy.
• History bloat requiring git lfs migrate — coordinate a repo-wide rewrite window.
• Assets that should never have been in git — move to an artifact registry or object storage.