Skip to main content

image guide

How to turn a video into a GIF for GitHub issues

Create small, readable GIFs for bug reports and pull requests: choose the right clip, FPS, width, and reproduction notes without uploading your video.

Updated 2026-05-26 8 min read Privacy-first workflow
Open Video to GIF Read the guide

Why GIFs still work well in bug reports

A good bug report shows the problem with as little friction as possible. A GIF plays inline in GitHub issues, pull requests, docs, chat tools, and release notes. The maintainer does not need to download a video, open a player, or scrub through a long recording. They see the broken interaction immediately.

GIF is an old format and it can become huge if you use the wrong settings. The trick is to convert only the few seconds that matter, reduce the width, and choose a frame rate that is smooth enough to understand but not so high that the file becomes unwieldy. ToolAtom's Video to GIF converter is built for this short-clip workflow and runs in your browser.

Step 1: record or prepare the source clip

If you do not already have a video, use Screen Recorder to capture the bug. Keep the recording short. Reproduce the issue once, pause just long enough to make the result visible, then stop. A 6-second clip is usually more useful than a 90-second video with setup steps, window switching, and dead air.

Before recording, zoom the app to a readable size, hide sensitive information, close notifications, and set the browser window to a normal width. If the bug depends on a viewport size, show that size in the issue text. If it depends on user permissions or feature flags, write that down separately instead of trying to reveal everything in the GIF.

  • Record one action - Click, drag, type, submit, or navigate once. Keep the clip focused.
  • Avoid private data - Use a test account or sample project when possible.
  • Keep cursor movement deliberate - Fast random movement is hard to follow in a low-FPS GIF.
  • Show final state - Let the broken state sit for a moment before stopping.

Step 2: choose GIF settings that GitHub readers can actually use

Open Video to GIF, upload the short video, and set the start and end time around the action. For most GitHub issues, use 8 to 12 frames per second and a width between 480 and 720 pixels. That is enough to show UI motion while keeping the file reasonable.

If the bug is a subtle animation glitch, increase the frame rate to 15 fps. If it is a form validation error, loading state, layout shift, or incorrect page transition, 8 fps is usually fine. Width matters more than people expect: a 1080px GIF can be several times larger than a 540px GIF because every frame stores many more pixels.

  1. Trim first - Choose only the segment that demonstrates the bug.
  2. Set width - Use 480px for chat and small UI, 720px for complex desktop screens.
  3. Set FPS - Use 8-12 fps for most issues, 15 fps for motion-sensitive bugs.
  4. Convert and preview - Watch the GIF once before attaching it to the issue.

Step 3: attach the GIF with a useful issue description

A GIF is evidence, not the whole report. Pair it with reproduction steps, expected behavior, actual behavior, environment, and any logs or console errors. The best GIF answers "what happened" while the text answers "how do I make it happen again".

When you upload the GIF to GitHub, place it near the top of the issue after a one-sentence summary. If the file is too large, trim the clip further, lower the width, reduce the frame rate, or split the report into a screenshot plus a shorter GIF. Do not attach a huge loop that distracts maintainers from the actual fix.

  • Summary - One sentence naming the broken behavior.
  • Steps to reproduce - Numbered steps, including test data if needed.
  • Expected result - What should happen.
  • Actual result - What the GIF shows happening instead.
  • Environment - Browser, OS, viewport, app version, and feature flags.

Optimization rules for small GIFs

GIF files get large because they store a sequence of images. You cannot make a long, high-resolution, high-frame-rate GIF small without losing quality. The practical optimization order is: shorten duration, reduce width, reduce frame rate, simplify visual noise, then compress if needed.

For UI bug reports, duration is usually the biggest win. A focused 4-second clip at 540px and 10 fps is easier to review than a 20-second clip at 1080px and 30 fps. If you need audio, GIF is the wrong format. Attach the original video or describe the audio issue in text.

Privacy benefits of browser-side conversion

Bug report videos can contain internal URLs, customer names, project keys, tokens, admin screens, or unreleased product features. Uploading the video to a cloud GIF maker can expose more than you intend. A browser-side converter keeps the source video on your device while frames are extracted and encoded locally.

That does not remove the need to inspect the final GIF. Watch it carefully before attaching. Check the address bar, account menu, sidebar, logs, and any open data table. Blur sensitive areas with a video editor before conversion if the source contains anything that should not be public.

A GitHub issue template for GIF bug reports

A GIF is not a replacement for a clear bug report. It is evidence. The issue still needs environment details, expected behavior, actual behavior, and reproduction steps. Put the GIF near the top so a maintainer can understand the failure quickly, then add the exact sequence of actions underneath. If the issue is intermittent, say how often it happens and whether the GIF shows the first attempt or a later attempt.

Use a short caption below the GIF. For example: "The save button stays disabled after changing the date field." This tells reviewers what they should look for before the animation loops. If the GIF shows a complex UI, add a timestamp note such as "watch the right panel after step 3." GitHub comments are busy spaces, and the best visual evidence points the viewer directly to the defect.

When the issue is fixed, the same GIF can become regression-test documentation. Link the pull request, explain which behavior changed, and keep the visual attached to the issue rather than scattering media across chat threads. This creates a searchable history for future maintainers who need to understand why the fix exists.

  1. Add the GIF - Place it near the top, after a one-line summary.
  2. Add reproduction steps - List the clicks or inputs needed to trigger the bug.
  3. Add environment details - Browser, OS, app version, account role, and any feature flags.
  4. Add expected behavior - Explain what should have happened instead.

When to use video instead of GIF

Use a video when the clip is long, needs audio, requires high visual fidelity, or includes multiple steps that should be paused and replayed. Use a GIF when the action is short, visual, and self-contained. For many GitHub issues, the ideal package is a short GIF plus plain-text reproduction steps.

The goal is not to make the fanciest media asset. The goal is to help the next engineer understand the bug quickly enough to reproduce and fix it. A small, focused GIF often does that better than a polished but heavy video.