GitHub Social Preview: size, design, and setup.
A repository cover has one small job: make the project recognizable before the link is opened. This guide explains the exact format, what to keep from screenshots, what to remove, and how to upload the result.
What is a GitHub Social Preview?
A Social Preview is the image GitHub associates with a repository when the repository link is shared. It gives link previews a visual identity beyond the repository name and description. GitHub lets repository administrators upload the image from the repository settings.
It is not the README banner, although the same artwork can be reused there if you choose. It is repository metadata: the image is used in social cards and link unfurls when the receiving service reads the repository's Open Graph metadata.
GitHub Social Preview size and file rules
GitHub accepts PNG, JPG, and GIF files under 1 MB. Its documentation recommends an image at least 640×320 and identifies 1280×640 as the best-display size. Both are a 2:1 ratio.
- Recommended working size: 1280×640 pixels.
- Aspect ratio: 2:1.
- Maximum file size: less than 1 MB.
- Accepted formats: PNG, JPG, or GIF.
Design at 1280×640, then inspect the result at 320×160. If the repository name and main idea disappear at that thumbnail size, the cover is not finished.
For the active product requirements, always check GitHub's official Social Preview documentation.
Design from repository evidence
The fastest option is a template with a repository name on the left and generic decoration on the right. It also removes the part that gives the repository an identity.
A stronger cover starts with three questions:
- Promise: What does this project let someone do?
- Proof: What can the repository honestly show to support that promise?
- Exclude: Which secondary details, UI fragments, and unsupported claims should stay out?
The answer might be a working interface, a character, a 3D object, a diagram, a waveform, or a visual system inferred from the project's real mechanics. The category alone—“game,” “tool,” or “library”—is not enough.
How to use screenshots without publishing a raw screenshot
A screenshot can be the strongest evidence and still be a poor finished cover. Browser chrome, clipped headings, debug text, unused panels, tiny controls, and empty states often become more visible once the image is reduced.
Keep
- the interaction or result that makes the product recognizable;
- project-owned artwork, characters, objects, and distinctive color relationships;
- enough interface context to make the action understandable.
Remove or rebuild
- browser bars, debug overlays, accidental clipping, and half-visible UI;
- duplicate headings when the cover already supplies the title;
- empty space that hides the actual gameplay or product task;
- connectors, panels, or decorative lines that have no semantic role.
Preserve identity, not every pixel. Recompose attractive source material. If it is already beautiful and representative, change less. If it is cluttered or incomplete, interpret more—but only within the repository's evidence.
A reliable cover workflow
- Inspect the repository. Read its README, meaningful code, rules, screenshots, SVGs, and primary visual assets.
- Run the product when practical. A working local web interface usually reveals more than a remote file tree.
- Diagnose the source material. Decide what is beautiful, recognizable, redundant, missing, or misleading.
- Choose the production route. Use editable SVG for typography and structure; use a screenshot or illustration only where it remains the clearest proof.
- Compose for the thumbnail. Keep the repository name, promise, and primary proof readable at 320×160.
- Validate mechanically. Confirm 1280×640 dimensions, a file below 1 MB, and a valid editable source.
- Review on light and dark surroundings. Social cards appear in both.
How to set a Social Preview on GitHub
- Open the repository on GitHub.
- Choose Settings. You need administrator access to the repository.
- Find the Social preview section.
- Choose Edit, then upload the PNG, JPG, or GIF.
- After saving, open the public repository page and check a fresh link preview. Cached social cards may take time to refresh on other services.
GitHub's UI and requirements can change, so use the official setup instructions as the final authority.
Common mistakes
Using text that becomes unreadable
Long feature lists and small captions may work at 1280 pixels and fail completely in an unfurled link. Reduce the message to one promise and a few grounded proof points.
Covering the most useful part of the screenshot
A fixed title card placed over the left half of every screenshot can hide navigation, gameplay, or the product result. Decide the crop only after identifying what the screenshot is proving.
Changing a project's dimensionality
A 3D or 3D-plus-toon-rendering project should not become a flat icon simply because flat SVG is convenient. Dimensionality is part of identity.
Adding meaningless lines
Connectors imply relationships. A line should connect real endpoints, show a real flow, divide real regions, or remain bounded inside a chart. If it does none of these, remove it.
Claiming proof that was never observed
Static repository inspection cannot prove that a build passed, a game ran, or a scene rendered. Keep visual claims within the evidence actually inspected.
Generate a GitHub Social Preview with RepoCover
RepoCover turns the workflow above into a Codex Skill. It creates an editable SVG and exact 1280×640 PNG, checks the output at full size and thumbnail size, and keeps GitHub upload as a separate action.
Use $skill-installer to install onovich/RepoCover from skill/repo-cover.