Quick answer: drag the video file into the issue or pull request comment box (or click the paperclip icon), wait for GitHub to finish uploading, and leave the generated URL on its own line so it plays inline. GitHub accepts .mp4, .mov and .webm videos and recommends H.264 for the widest browser support.
The size limits, from GitHub's "Attaching files" docs (checked October 2026):
- 10 MB for images and GIFs.
- 10 MB for videos in a repository owned by a user or organization on a free GitHub plan.
- 100 MB for videos in a repository owned by a user or organization on a paid GitHub plan. To go over 10 MB there, you must be an organization member, an outside collaborator, or on a paid plan yourself.
- 25 MB for all other file types.
If your recording is bigger than that, trim it, compress it to an H.264 MP4, or paste a link to it instead. The rest of this post covers each of those, plus copyable issue and pull request templates that ask contributors for a short repro recording.
How do you attach a screen recording to a GitHub issue?
The same steps work for a new issue, a pull request description, and any comment on either.
- Open the comment box. Start a new issue, edit a pull request description, or scroll to the comment field at the bottom of the thread.
- Add the file. Drag the video from your desktop or file manager and drop it into the text area. If you prefer a file picker, click the paperclip icon. On an issue it sits below the comment box; on a pull request it is also in the formatting bar above the comment box.
- Wait for the upload. GitHub uploads the file immediately and updates the text field with an anonymized URL for the file. Wait until that URL appears before you submit, especially for a large video on a slow connection.
- Keep the URL on its own line. Write your explanation above or below it, with a blank line in between. A video renders as a player only when its URL is the only content in its paragraph. Inside a sentence it renders as a plain link. GitHub's CLI docs state the same rule for videos attached from the command line.
- Check the Preview tab. You should see a video player, not a bare URL. Then submit.
For screenshots, many browsers also let you paste an image straight from the clipboard into the box. Video files are easier to drag in from disk.
What renders inline: images (PNG, GIF, JPEG, SVG) and videos (.mp4, .mov, .webm). Other supported files, such as a .log, .json, .zip or .pdf, show up as links to the file. GitHub accepts those in issue, pull request and discussion comments, which is handy for attaching a saved console log next to the video, as long as it stays under 25 MB. For getting those logs out of the browser in the first place, see how to record your screen with console logs.
One codec caveat from GitHub itself: which codecs play depends on the browser. A file that plays in your browser may not play in a reviewer's. H.264 in an MP4 container is the safe default, which is why it is worth converting a browser-made WebM or a .mov before you attach it (more on that below).
What are GitHub's video upload size limits?
The limit depends on who owns the repository and on who is uploading, not on whether it is an issue or a pull request.
| What you attach | Limit |
|---|---|
| Images and GIFs | 10 MB |
| Video, repo owned by an account on a free GitHub plan | 10 MB |
| Video, repo owned by an account on a paid GitHub plan | 100 MB (see the note below) |
| All other files | 25 MB |
Source: docs.github.com, Attaching files, checked October 2026.
The note that trips people up: to upload a video larger than 10 MB to a repository on a paid plan, you have to be an organization member, an outside collaborator, or on a paid plan yourself. GitHub's docs only allow uploads over 10 MB there for organization members, outside collaborators and people on a paid plan, so a contributor on a free personal account who files an issue on a big company's open-source repo should plan for 10 MB, even though the repository owner pays for GitHub. If you maintain a project, write your templates around 10 MB and treat anything bigger as a bonus.
Issue forms with a dedicated upload field (covered below) have their own table on the form schema page, which lists 100 MB for .mp4, .mov and .webm. The two pages do not say how they interact, so 10 MB is still the number to give contributors.
Do not confuse these with repository file limits, which come up in the same searches. Those apply to files you commit, not to attachments in comments: a file added to a repository through the browser can be no larger than 25 MiB, Git warns above 50 MiB, and GitHub blocks files over 100 MiB unless you use Git Large File Storage (see About large files on GitHub). A video committed to the repo also does not play inline in an issue the way an attachment does.
Two more things worth knowing before you attach anything:
- Public means public. GitHub's docs say that for public repositories, uploaded files can be accessed without authentication. Anyone with the URL can watch your recording. In private and internal repositories, only people with repository access can view uploads.
- Check the frame for secrets. Screen recordings catch API keys in a terminal, customer emails in an admin panel, and tokens in a URL bar. Scrub through the video before you post it, and blur anything sensitive with a tool like the video region blur tool.
Can you attach a video from the command line?
Yes, with a recent GitHub CLI. The --attach flag arrived in gh 2.99.0 (GitHub changelog, September 2026), so if gh says the flag is unknown, update gh first. It works on gh issue create, gh issue edit, gh issue comment, gh pr create, gh pr edit and gh pr comment. The flag uploads the local file and writes the URL into the body, so it renders the same way a browser upload does. You need push access to the repository, and the CLI only uploads image and media files.
gh issue comment 123 --attach ./repro.mp4To place the video at a specific spot in a longer body, reference the local file in your Markdown and attach the same file. The CLI rewrites the local path to the uploaded URL. Keep the video reference alone in its paragraph so it becomes a player:
Clicking Save on the settings page logs the user out:

Happens on every browser I tried.gh issue create --title "Save logs the user out" \
--body-file ./body.md \
--attach ./repro.mp4Alt text works for images (add #your alt text after the path) but not for videos. Details are on GitHub's Attaching files with GitHub CLI page. This is especially useful when a coding agent opens the pull request: it can attach its own before/after capture without anyone opening a browser.
What should you do when the recording is too big?
Work through these in order, and stop as soon as the file fits.
1. Trim it first
Most bug recordings are long because of the setup: logging in, navigating, waiting for a build. The reviewer needs the last few seconds before the bug and the bug itself. Cutting a two-minute take down to 30 seconds cuts the file to roughly a quarter. You can cut ranges with the free Trim & Split Video tool or any editor, and describe the setup steps in text instead.
2. Compress it to an H.264 MP4
Screen recordings straight from a recorder are often encoded for quality, not size. A quick size check: file size is roughly bitrate times duration. To fit 60 seconds into 10 MB, the whole file has to average about 1.3 megabits per second (10 MB is 80 megabits, divided by 60 seconds). That is enough for readable UI at 1280 pixels wide, but not for a 4K desktop at full resolution, so scaling down matters as much as the quality setting.
The Video Compressor takes MP4, MOV or WebM and returns an H.264 MP4, which matches GitHub's codec recommendation. Its Balanced preset caps width at 1280 pixels and Smaller caps it at 854. If you prefer the terminal, ffmpeg does the same job:
ffmpeg -i repro.mov -vf "scale='min(1280,iw)':-2" -c:v libx264 -crf 30 -preset slow -pix_fmt yuv420p -c:a aac -b:a 96k -movflags +faststart repro.mp4Raise -crf for a smaller file, lower it for a sharper one. Keep -pix_fmt yuv420p: without it, a ProRes or 4:4:4 source produces an H.264 profile that most browsers will not play, which brings back the problem you were trying to fix. -movflags +faststart lets the video start playing before it has fully downloaded. If the audio adds nothing, drop it with -an instead of the two audio options. For more on getting a file under a hard size cap, see how to compress a video for WhatsApp, Discord and email.
3. Convert WebM or MOV to MP4
GitHub accepts WebM and MOV, but playback depends on the viewer's browser. Browser-based recorders usually save WebM, and macOS saves MOV. Converting to an H.264 MP4 fixes the "it plays for me but not for the reviewer" problem. Use the WebM to MP4 or MOV to MP4 converters, or read the walkthrough on converting WebM to MP4.
4. Use a GIF only for short, silent clips
A GIF autoplays and loops right in the issue body, which is nice for a three-second animation glitch. But GIFs share the 10 MB image limit and are much larger than MP4 for the same footage, so they only work for very short clips at a small width. MP4 to GIF handles the conversion, and these GIF settings keep the file small. Anything with narration or longer than a few seconds should stay an MP4.
5. Paste a link instead
If the recording is long, has narration that matters, or will not shrink below the limit, upload it somewhere else and paste the link into the issue. Any host works as long as the people reading the issue can open it without requesting access. Check that before you post. A cloud drive file left on its default restricted sharing, for example, makes every maintainer request access, and a link that asks for a login is a dead end for someone triaging fifty issues.
Why did my GitHub video upload fail or show up as a link?
When a video will not attach, or posts as a download link instead of a player, it is usually one of these:
- The file is over the limit. Check the size against the table above, including the 10 MB rule for contributors outside a paid organization. Trim or compress it.
- The format is not supported. GitHub takes
.mp4,.movand.webmvideos. An.mkvor.avihas to be converted first, for example with MKV to MP4 or AVI to MP4. - The codec is not H.264. Recent iPhones and Macs often save video as HEVC (H.265), and QuickTime or editing apps can export ProRes. Those files have the right extension but may preview for you and then fail to play for others, or show as a link. Re-encode to an H.264 MP4 with the command above or the Video Compressor. To check a file's codec, run
ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,pix_fmt repro.movand look forh264andyuv420p. - The upload had not finished. If you submit before the file URL appears in the text box, the comment goes up without the video. Edit the comment and attach it again.
- The URL shares a paragraph with text. Move it onto its own line with a blank line above and below.
Can you put a video in a GitHub README?
Yes. GitHub's video upload announcement says upload works in repository Markdown files such as READMEs, as well as in issue, pull request and discussion comments. Edit the README on github.com, drag the video into the editor, and keep the resulting URL on its own line. The same size limits and codec advice apply. Use the Preview tab before committing to confirm it renders as a player. Other Markdown renderers, such as a docs site built from the same README, may show that URL as a plain link.
When is a link better than an attached file?
An attached file has real advantages. It lives with the issue for as long as the issue exists, it plays inline, and nobody has to leave GitHub. For a short clip that fits, attach it.
A link is the better choice when:
- the recording is longer than a minute or two and will not fit without becoming unreadable;
- the narration carries the explanation, and readers benefit from a transcript they can skim or search;
- you want control over who can watch, since files uploaded to a public repository are readable by anyone with the URL;
- a coding agent will work from the issue and needs a transcript or written steps, not just a video file.
The trade-off is that a link depends on the host. If the account is deleted or the sharing setting changes, the issue loses its evidence. GitHub also renders an external link as a link, not as an inline player.
Clipy is built for the link route. Recording requires a Clipy account, but the people you share with can watch without one. Each recording gets a transcript and key moments, and on the recording's page Copy for agents → GitHub issue copies issue-ready Markdown with a title, the watch link, an agent-context link and a checklist, which you paste into the issue. Connect GitHub and Clipy creates the issue from the recording for you. It is free to start with a 7-day free trial, no card needed, and Pro is $9 a month or $72 a year. If a project would rather keep everything on GitHub, you can download the recording, trim and compress it, and attach the MP4 instead.
How do you ask contributors for a repro recording?
Put the request in your issue template, with the size limit stated, so nobody has to ask in a comment after the fact. Below are two versions. Both are tool-neutral: any screen recorder works, from the one built into the operating system to a browser extension.
Issue form: .github/ISSUE_TEMPLATE/bug_report.yml
Issue forms render as a structured form instead of a blank text box, and the answers are converted to Markdown in the issue body. This one follows GitHub's issue form syntax and form schema:
name: Bug report
description: Something is broken. A short screen recording helps us fix it faster.
title: "[Bug]: "
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Thanks for reporting this. A 10 to 60 second screen recording of the bug
is often the quickest way for us to see it. Any screen recorder is fine.
Keep video files under 10 MB, or paste a link instead.
- type: textarea
id: what-happened
attributes:
label: What happened?
description: What did you do, what did you expect, and what happened instead?
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce
placeholder: |
1. Go to ...
2. Click ...
3. See the error
validations:
required: true
- type: upload
id: recording
attributes:
label: Screen recording
description: Drag in an .mp4, .mov or .webm file. MP4 (H.264) plays in the most browsers. Under 10 MB is safest.
validations:
required: false
- type: input
id: recording-link
attributes:
label: Or a link to the recording
description: If the file is too big, paste a link. Please check that it opens without signing in.
placeholder: https://
- type: textarea
id: environment
attributes:
label: Environment
value: |
- OS:
- Browser and version:
- App or package version:
- type: textarea
id: logs
attributes:
label: Console or log output
description: Paste any errors from the browser console or terminal. This is formatted as code automatically.
render: shellA few details that matter:
- Labels must already exist. GitHub only adds labels that exist in the repository, so create any extra labels (such as
needs-triage) before you add them to thelabelslist. - The
uploadfield gives contributors a dedicated drop zone. It takeslabelanddescription, plus optionalrequiredandaccept(a comma-separated list of allowed extensions) validations. - Do not add
renderto a field where you want attachments. GitHub's docs say that whenrenderis set, the text area "will not expand for file attachments or Markdown editing." That is why only the log field above uses it. The other text areas still accept a dragged-in video. requiredonly works in public repositories. Leave the recording optional anyway. Some bugs cannot be recorded, and a required upload makes people abandon the form.- Issue forms are in public preview, according to GitHub's docs. If your GitHub instance rejects the
uploadtype, delete that block; contributors can still drag a video into any text area that does not userender.
To stop people skipping the form, add .github/ISSUE_TEMPLATE/config.yml with blank_issues_enabled: false. People with write access still see a blank issue option labeled "Maintainers only"; everyone else only sees your templates.
Or a Markdown template: .github/ISSUE_TEMPLATE/bug_report_simple.md
If you prefer a plain template that pre-fills the issue body, this is the short version. Pick one of the two templates, not both: they ask for the same things, and GitHub requires every template name to be unique, so if you ever keep both, give them different name values. The HTML comments are hidden when the issue renders.
---
name: Bug report (simple)
about: Something is broken
title: '[Bug]: '
labels: bug
assignees: ''
---
### What happened?
### Steps to reproduce
1.
2.
3.
### Screen recording
<!-- Drag an .mp4, .mov or .webm file onto this line, or paste a link.
Under 10 MB is safest. Leave the video on its own line so it plays inline. -->
### Environment
- OS:
- Browser and version:
- App or package version:For what to put in the rest of a good report, see how to write a bug report. If your reporters are customers rather than developers and will never open GitHub, a recording request link is a better fit than an issue template.
How do you show before and after in a pull request?
For a UI change, a short recording of the old behavior next to the new one answers the reviewer's first question before they ask it. Record both on the same screen size, with the same steps, so the only difference is your change. Keep each clip short, and put each video on its own line under its own heading:
## Before / after
**Before:** the Save button stays enabled while the request is in flight.
https://github.com/user-attachments/assets/your-before-video
**After:** the button disables and shows a spinner until the request finishes.
https://github.com/user-attachments/assets/your-after-videoThe URLs above are placeholders. Drag in your own files and GitHub fills in the real ones. To make this a habit for the whole team, add a .github/pull_request_template.md file. GitHub shows its contents in the body of every new pull request once the template is on the default branch:
## What changed
## How to test
## Before / after
<!-- For UI changes, attach a short recording of each.
Put each video on its own line so it plays inline. -->
**Before:**
**After:**
Closes #If the change is easier to explain by walking through it than by writing it up, you can record the walkthrough once and turn it into the description with Recording to PR Description, then edit the text before you paste it. It is optional; the template above works with any recorder. Teams that ask coding agents to attach this kind of evidence to their own pull requests may also want this guide to requiring proof of work on agent PRs.
Common questions
Why does my video show up as a link instead of a player?
The URL is probably sharing a line or paragraph with other text. Put it on its own line with a blank line above and below. If it is a link to an external host rather than a GitHub upload, it will always show as a link.
Why does the video play for me but not for a reviewer?
Codec support differs between browsers. GitHub recommends H.264, so re-encode WebM, HEVC or ProRes recordings to an H.264 MP4 and attach that instead.
Can I upload a video larger than 10 MB?
Only in a repository whose owner is on a paid GitHub plan, where the video limit is 100 MB. GitHub's docs allow uploads over 10 MB there for organization members, outside collaborators and people on a paid plan, so a contributor on a free personal account should plan for 10 MB. Otherwise trim, compress, or link.
Does the same work on pull requests and comments?
Yes. GitHub's docs describe the same upload for issues, pull requests and comments, with the same size limits. For pull requests the attach button also appears in the formatting bar.
Who can see a video I attach?
In a public repository, anyone with the file URL, without signing in. In private and internal repositories, only people with access to the repository.