LFS to GitHub Pages prototype

GitHub Pages doesn't serve files that are stored in LFS, even though this has been consistently requested for years. This is understandable: It would instantly turn GitHub Pages from the world's largest code hosting service to the world's largest file hosting service.

That said this repository showcases a simple partial work-around: How to serve LFS files through GitHub Pages (within GitHub's file size limits)?

A typical use case is when you would like to use LFS to track large, 10-100 MB, binary files (.pdf, .jpg, .png, .mp3, .mp4, etc.) so they don't weigh down the commit history — but you would also like to serve these files through GitHub Pages.

⚠️ Please note that this technological demo, which has been reviewed by GitHub Trust & Safety, is in no way intended to circumvent GitHub Pages' Terms of Service and must only be used within GitHub Pages' usage limits (e.g., at the time of writing, a hard limit of 1 GB of storage per repository, and a soft limit of 100 GB/month of bandwith).

Demo

This repository has been configured to store *.webp files with Git LFS.

This is the file image.webp as stored in the main branch:

After GitHub Actions' continuous integration, this is the file image.webp as stored in the gh-pages branch:

You can confirm that this file is being served through GitHub Pages:

https://jlumbroso.github.io/lfs-to-github-pages/image.webp

How It Works

1. First, the continuous integration fetches the latest version of the repository's main branch, fetching the files stored through Git-LFS:

   - name: 🛎️ Checkout
     uses: actions/checkout@v3
     with:
       fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
       lfs: true # Fetch large files

2. We remove the Git LFS hooks, and then remove all the Git metadata associated with the repository:

   - name: ❌ Turn off LFS
     run: >-
       git lfs uninstall;
       rm -Rf .git;
       rm .gitattributes;

3. We deploy the files we have checked out (including the files stored through Git LFS) to the gh-pages branch:

   - name: 🚀 Deploy to `gh-pages` branch
     uses: peaceiris/actions-gh-pages@v3.9.0
     with:
       github_token: ${{ secrets.GITHUB_TOKEN }}
       publish_dir: ./
       publish_branch: gh-pages
       user_name: "github-actions[bot]"
       user_email: "github-actions[bot]@users.noreply.github.com"

Copyright & License

The image "Robots Cutting Books" is copyrighted 2022 by the artist, Jérémie Lumbroso, and is made available here under the CC BY-ND 4.0 license, which means you can distribute it, with attribution, for any purpose, as long as you don't distribute modified versions of it.

The code in this repository is provided under the MIT license.