How to Share Large Files in GitHub Issues, READMEs, and Pull Requests
— Written by Brendan, Founder of FileShot.io
GitHub is where most of the world’s code lives — but it has a persistent size problem. File attachments in issues and pull requests are capped at 25 MB. GitHub LFS extends this for files stored in repositories, but has its own bandwidth limits. GitHub Releases allows larger assets (up to 2 GB per file), but that’s not the right tool for a crash dump attached to a bug report, or a build artifact shared in a PR comment.
This guide covers every situation where GitHub’s size limits get in the way and the cleanest way to work around each one.
GitHub File Size Limits: A Quick Reference
| Feature | Limit |
|---|---|
| Issue / PR file attachment | 25 MB |
| Single file in a repository | 100 MB (hard limit) |
| GitHub LFS file size | 5 GB |
| GitHub Release asset | 2 GB |
| Images in README (from repo) | No display limit, but >100 MB can’t be committed |
The 25 MB attachment cap is the one most people run into day-to-day. Here’s what to do in each scenario.
Scenario 1: Attaching a Large File to a GitHub Issue
The most common frustration: you’re filing a bug report and the crash dump, HAR file, screen recording, or log archive is over 25 MB. GitHub’s drag-and-drop attachment simply refuses it.
The fix
- Go to FileShot.io and drop your file onto the upload zone.
- The file encrypts in your browser (AES-256-GCM) and uploads. You get a link.
- Paste the link into the GitHub issue. Anyone with it can download and decrypt in their browser — no account required.
The link contains the decryption key in the URL fragment (#key=...), which browsers never send to the server. Even FileShot can’t read the file. If the data is sensitive (PII in logs, internal details), you can also enable password protection before sharing.
What to set
- Expiration: 30–90 days is usually enough for an open issue. Set longer if the issue might take months to resolve.
- Max downloads: Leave unlimited unless you have a reason to restrict access.
- Password: Use it if the log file contains credentials, emails, or anything you wouldn’t want public. Share the password in a separate message or DM.
Scenario 2: Embedding a Large File Link in a README
You want to reference a dataset, a compiled binary, a demo video, or a supplementary document from your README without committing it to the repository. Git is not the right tool for binary blobs, and GitHub LFS adds complexity for something that doesn’t need version history.
The fix
Upload the file to FileShot and embed the link in your README like any other link:
[Download sample dataset](https://fileshot.io/f/abc123#key=xyz)Or for a badge-style download button:
[](https://fileshot.io/f/abc123#key=xyz)One note: since the free tier expires links after 90 days, README links should use a Pro or Creator account’s unlimited-expiry setting, or you’ll need to refresh the link periodically.
Scenario 3: Sharing Build Artifacts in a Pull Request
CI/CD pipelines often produce artifacts — test reports, coverage output, compiled binaries, screenshots — that reviewers need to see before approving. GitHub Actions can store these as artifacts, but they expire in 90 days and require logging into the GitHub interface to access. For sharing with external reviewers or clients, that’s friction that often isn’t worth it.
The fix
Add a step to your CI pipeline that uploads the artifact to FileShot and posts the link as a PR comment. Using the FileShot API (available on Creator tier), or just a simple curl command in a workflow step:
# example: upload any build output and get back a download link
curl -F "file=@dist/app.AppImage" https://api.fileshot.io/uploadWithout API access, you can still manually upload from the FileShot web interface and paste the link into a PR comment.
Scenario 4: Distributing a Private Pre-Release Build
You’re not ready for a public GitHub Release, but you want a specific group of testers to download a build. You could create a private draft release, but that requires all testers to have GitHub accounts with repo access. FileShot’s download limit feature is often simpler here.
The fix
- Upload the build to FileShot.
- Set Max Downloads to the number of beta testers you have.
- Optionally set a password. Share the link and password with your test group.
- Once the download limit is reached, the link stops working automatically.
Scenario 5: Sharing a Large Video in an Issue or Discussion
Screen recordings of bugs are invaluable for maintainers, but a 2-minute 1080p recording is easily 100–200 MB — well over the 25 MB cap. GitHub’s own workaround (compressing the video to under 25 MB) often destroys quality to the point of being useless.
The fix
Upload the full-quality recording to FileShot and paste the link. Set a longer expiry (90–90 days) so the link stays live while the issue is open. The maintainer can watch or download it without any account creation.
What About GitHub LFS?
GitHub Large File Storage is designed for files that belong in version history — large assets for a game project, high-res design files that increment with each release, etc. It’s not designed for ephemeral sharing. It also comes with bandwidth limits: free accounts get 1 GB of LFS bandwidth per month, which runs out fast if you have active contributors downloading the same large files. Overages cost money.
For one-time file sharing (bug attachments, artifacts, builds), LFS is the wrong tool. FileShot is cheaper (free), simpler (drag-drop, get link), and doesn’t leave files in repo history forever.
Summary
GitHub’s 25 MB attachment cap will stop you at some point if you work on any project with large files. The solution is straightforward: upload to FileShot, get a link, paste it into GitHub. The file is encrypted in the browser, the link works for anyone without an account, and it expires automatically when you no longer need it.