When Should Screenshots Live in Git, and When Should They Be Hosted Elsewhere?

A screenshot can turn a vague bug report into something you can act on. But once you capture it, where should it live: in the repository, attached to the issue, or at a separate URL? The right choice depends on whether the image is part of the project, evidence for one discussion, or an asset other people need to reuse.

Keep it in Git when it belongs to the project

Commit an image when it explains the product or documentation and should change alongside the code. That might be a screenshot showing the expected output of a documented command, or a diagram that a pull request updates with an architecture change. A stable path also makes the image easy to reference from a README or docs page.

Use a descriptive filename, add useful alt text, and export only the dimensions and quality the page needs. Large binaries can add weight to repository history even after you replace them. GitHub’s large-file guidance explains the file and repository size limits to keep in mind.

Attach it when it is evidence for one conversation

A screenshot of a one-off layout bug usually belongs with the issue or pull request where the fix is discussed. The image stays beside the reproduction steps and reviewer comments, but it does not become a permanent project asset after the conversation is resolved.

Check the visibility of the issue before sharing. An attachment that only teammates can open will not help a reader following a public tutorial. Redact access tokens, email addresses, customer data, and unrelated browser tabs before uploading; cropping or marking up the image itself is safer than relying on a note in the surrounding thread.

Host it separately when it needs to be reused

A hosted image makes sense when several repositories or a content system need the same asset, or when the destination accepts a URL but cannot store the file in your repository. This adds a dependency: the page now relies on another service keeping the image available to the intended readers.

For a Markdown image, the URL should return the image itself. For example:

![Menu overlapping at a narrow viewport](https://example.com/screenshots/menu-overlap.png)

A share or preview page may open perfectly in a browser tab but still fail inside an image embed, because the embed expects image data rather than a webpage. Use a share page when someone should open a normal page to inspect the file; use the direct media URL when the document needs to render the image inline.

Disclosure: Media2URL is my project. Its Image to Link tool returns a direct media URL for embeds and a separate share page for browser viewing. It is one possible way to host a local screenshot; whichever service you use, check its access and expiry settings before you make the link part of documentation.

A quick decision check

• Will the image change with the code or docs? Keep it in the repository.
• Is it evidence for one bug report or review? Attach it to that discussion.
• Does it need the same address in several public places? A separate host may fit.
• Can a reader open the image without your account, and will it stay available as long as the page needs it?

My default is to commit stable project documentation, attach temporary evidence to its discussion, and host reusable public assets only when the URL’s lifetime and access rules are clear. Keep the original file somewhere you control, then open the final URL in a private browser window before you rely on it.