GitHub Pages is a static host, so embedding video means either an iframe pointing at YouTube or Vimeo, which handles encoding and bandwidth for you, or a self-hosted video tag pointing at a file committed to the repository, which works but is bounded by GitHub’s repository size limits, and Git LFS does not serve files on Pages at all. For anything beyond a short clip, the iframe is the practical answer; for a self-hosted file, know the ceiling before you hit it.
Search results split into two separate problems that keep getting merged into one answer: GitHub’s README markdown renderer, which genuinely does not support video embeds outside of drag-dropped attachments, and an actual GitHub Pages site, which is just an HTML page and can use a normal video tag or iframe like any other static site. Most tutorials answer the README question when the person asked about their Pages site. Here is both, kept separate.
Table of contents
- Two different questions that get confused
- Embedding via YouTube or Vimeo (the practical default)
- Self-hosting a video file directly
- The repository size and bandwidth reality
- Why Git LFS does not solve this
- What to do once the video needs real storage
- How this fits the rest of the stack
- FAQ
Two different questions that get confused
A GitHub README is markdown, rendered by GitHub’s own renderer, which does not support a raw video tag or an image-style embed for video files; the only way to get a playable video in a README is to drag the file into an issue or pull request comment box and let GitHub host it as an attachment, then paste the resulting link.
A GitHub Pages site is a different thing entirely: it is a folder of HTML, CSS and JS served as a static website, and it renders exactly the HTML you write, including a normal video tag or an iframe. If your question is about a page at username.github.io, ignore every README-specific answer; they do not apply.
Embedding via YouTube or Vimeo (the practical default)
For any video longer than a few seconds, hosting it yourself is rarely worth the bandwidth cost. An iframe embed from YouTube or Vimeo handles encoding for multiple resolutions, adaptive bitrate, and a CDN, none of which a static file on GitHub Pages gives you.
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/VIDEO_ID"
title="Video title"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen>
</iframe>Wrap it in a container with aspect-ratio: 16 / 9 and width: 100% so it resizes on mobile instead of overflowing a fixed pixel width, which is the most common visual bug with copy-pasted embed code.
Self-hosting a video file directly
A short clip, a demo GIF-replacement, or a background video can live in the repository and play from a plain video tag, no third party involved.
<video width="640" height="360" controls preload="metadata">
<source src="/assets/demo.mp4" type="video/mp4">
Your browser does not support the video tag.
</video>preload=“metadata” fetches just enough to show the first frame and duration without downloading the whole file until the visitor presses play, which matters because GitHub Pages serves everything in the repository over the same bandwidth allowance as the rest of the site.
The repository size and bandwidth reality
GitHub itself recommends repositories stay under a size that is comfortable to clone and warns against files over 100MB, which most video files exceed quickly, even a short clip at reasonable quality. A repository is not designed to be a video CDN, and treating it as one shows up first as slow clone times for anyone else working on the project.
GitHub Pages sites are also subject to GitHub’s documented usage guidelines, intended for standard project sites rather than heavy media serving. A single popular page with a large embedded video can approach those limits in a way a page of text and images never will.
Why Git LFS does not solve this
Git Large File Storage looks like the obvious fix for a large video file in a repository, but GitHub Pages does not serve files tracked with LFS; it serves the small pointer file LFS leaves behind instead of the actual video, which is why a video that plays fine when cloned locally shows as broken on the published site. This is one of the most common surprises for anyone who has already set up LFS for other large assets.
If a video needs to be self-hosted at any meaningful size or traffic, it needs actual object storage or a media host behind it, not a git repository serving as a makeshift CDN.
What to do once the video needs real storage
Past a certain point, the honest answer is that GitHub Pages was never meant to serve media at scale, and reaching for a dedicated video host or object storage in front of a CDN is not a workaround, it is the correct architecture. If the site itself has outgrown a purely static repository, for example because it needs uploaded content or storage that changes at runtime, that is also the point where a static host with a real bandwidth allowance, rather than a git repository, becomes the right home for the rest of the project too.
A static site on RunxBuild, for instance, is still built from a repository like GitHub Pages, but with a real bandwidth allowance behind it rather than a repo hosting guideline, which is the more honest fit once video, images or downloads add up. See getting started with GitHub Pages for the baseline before deciding you have outgrown it.
How this fits the rest of the stack
If a project starts adding real media weight, whether video, high-resolution images, or downloadable files, that bandwidth is worth pricing before a popular page finds the limit for you: the RunxBuild hosting calculator shows what the same site costs with 120GB of bandwidth included. Static sites on RunxBuild covers the build-from-repository path once GitHub Pages’ guidelines start feeling tight, and the dashboard is where a repository gets connected.
Useful related references:
- GitHub Pages SEO: What You Can Fix and What You Cannot
- Getting Started With GitHub Pages, and the Exact Point You Outgrow It
- GitHub.io Blog Template: Picking a Jekyll Theme, Wiring It Up, and Knowing When You Have Outgrown Pages
- Deploying from GitHub on RunxBuild
FAQ
Can GitHub Pages host video files?
Yes, as a static file served with a normal video tag, but with GitHub’s repository size guidance in mind, files over roughly 100MB are discouraged. For anything longer than a short clip, an embedded YouTube or Vimeo iframe is the more practical route and does not use the repository’s storage at all.
Why won’t my video play on GitHub Pages?
The most common cause is Git LFS: GitHub Pages serves the LFS pointer file, not the actual video, so a file that works locally shows as broken once published. Track the video normally in git, without LFS, or move it to an external host.
Can I embed a video in a GitHub README?
Not directly. GitHub’s markdown renderer does not support a video tag or image-style embed for video files. The workaround is dragging the file into an issue or pull request comment box, which uploads it as a GitHub-hosted attachment you can then link from the README.
What is the file size limit for GitHub Pages?
There is no single hard number, but GitHub recommends repositories stay small for cloning and flags files over about 100MB. Pages sites are also covered by GitHub’s usage guidelines, meant for standard content rather than heavy media serving.
Should I self-host video or use YouTube on GitHub Pages?
Self-host only short clips where you want no third-party branding and the file stays well under the size guidance. For anything longer, YouTube or Vimeo handles encoding, adaptive quality and bandwidth in a way a static repository file cannot.