GitHub LFS Mysteries: Why `git push --mirror` Can Succeed with Missing Objects (and What It Means for Your GitHub Monitoring Dashboard)

The Curious Case of Missing LFS Objects and Successful Pushes

Imagine successfully pushing a Git repository to GitHub, only to discover later that crucial large files (managed by Git LFS) are missing. This perplexing situation, recently highlighted in a GitHub Community discussion, reveals a nuanced interaction between Git, Git LFS, and GitHub's server-side validation. It's a scenario that can create blind spots in your software development tracking and lead to broken repositories.

Aakash4792 described a situation where a source repository had missing LFS objects. A mirror clone worked, but attempting to fetch LFS objects failed with 404 Object does not exist on the server errors. What was truly confusing was the inconsistent behavior of git push --mirror. On one occasion, pushing this broken mirror to a new GitHub repository failed with the expected GH008 error, indicating unknown LFS objects. However, on a subsequent attempt to a brand-new empty repository, the exact same git push --mirror command succeeded without a hitch. Yet, cloning this newly pushed repository and running git lfs fetch --all confirmed that the LFS objects were still missing.

error: failed to fetch some objects from 'https://github.com/ORG/EmptyRepo9.git/info/lfs'

Understanding Git LFS and Push Mechanics

The core of this mystery lies in how Git and Git LFS operate. When you use Git LFS, the actual large files are not stored directly in your Git repository. Instead, Git stores small "pointer files" that reference the large objects. These pointers contain metadata like the object's SHA-256 hash and size. During a standard git push (or git push --mirror), Git primarily transfers the Git history and these pointer files.

The upload of the actual LFS objects is a separate, decoupled process, typically handled by Git LFS hooks that run alongside the Git push. GitHub utilizes a "pre-receive hook" on its servers. This hook is designed to validate if the LFS payloads referenced by the pointer files being pushed have actually been uploaded to GitHub's LFS storage. If they haven't, the hook is supposed to reject the Git push with the notorious GH008 error.

The Inconsistent GH008 Error: A GitHub-Side Enigma

The inconsistency observed by Aakash4792, where GH008 appeared one day but not the next for the same broken LFS history, points to a transient infrastructure issue on GitHub's side. Community replies suggest that GitHub's pre-receive hooks can sometimes time out, be temporarily bypassed during heavy server load, or behave differently, especially during massive --mirror pushes to empty repositories. When this validation hook fails to run or is disabled to prevent bottlenecks, the standard Git push (containing only the pointers) succeeds, leaving the destination repository with valid Git history but missing LFS objects.

This scenario highlights a critical blind spot for teams relying solely on standard git push success messages for software development tracking. A successful push doesn't always guarantee the integrity of your LFS content.

Resolving Broken LFS Repositories

If you find yourself with a repository that has missing LFS objects, the primary solution is to locate a local copy of the repository that still contains the actual LFS files. From that working local copy, you can then run:

git lfs push --all origin

This command attempts to push all referenced LFS objects to the remote. If the original files are irrecoverable, you might need to rewrite your Git history (e.g., using git filter-repo) to remove the broken LFS pointer files entirely, effectively purging the references to the missing large files.

Community Insights: Key Takeaways

• A successful git push --mirror does not inherently validate the presence of Git LFS objects on the remote server.
• Git LFS pointer files are treated as regular Git objects, separate from their large binary payloads.
• Inconsistent GH008 errors are likely due to transient issues with GitHub's server-side pre-receive hooks, possibly related to load or timeouts.
• For effective software project metrics and repository health, it's crucial to understand these underlying mechanics.
• Such inconsistencies underscore the need for robust github monitoring dashboard tools that go beyond basic Git status to verify LFS object integrity. Always verify LFS content independently, especially after significant repository operations.