Quick answer: A GitHub repository's social preview is the image shown when the repo is shared on X, LinkedIn, Discord, Slack, and in other link unfurls. GitHub recommends 1280×640 pixels — a 1.91:1 ratio — as a PNG, JPG, or GIF under 1 MB. Images as small as 640×320 are accepted, but upscaling softens them.

The official specs

Spec Value
Recommended size 1280×640 px
Minimum accepted 640×320 px
Ratio 1.91:1
File types PNG, JPG, GIF
File size Under 1 MB
Where it is set Repo Settings → General → Social preview

Without a custom preview, GitHub shows a blank or a generic repository card. For an open-source launch or a side project, that blank is wasted distribution — the open source launch guide and the developer tool launch guide both treat the preview as a required asset.

How the preview appears

The 1280×640 image is rendered in very different contexts:

  • Large in a social post.
  • Medium in a chat unfurl.
  • Small in a search or feed card.
  • Alongside the repo name and description.

The design must survive the small version.

What to put on it

A good repo preview answers two questions in one glance: what it is, and why it is worth clicking. The proven layouts:

  1. The identity card. Logo or mark, project name, a one-line tagline. The safest default.
  2. The code card. The name plus a short, real snippet or a one-line CLI command. The visual says "this is a tool."
  3. The diagram card. A small before/after or a three-box flow showing the problem the repo solves.
  4. The proof card. Name, tagline, and one factual metric (downloads, stars, or a benchmark — only if it is true and current).

The tagline should be the same line as the value proposition on the site, not a different sentence.

The design rules

  • One line of statement, maybe two short lines.
  • The project name is the largest text; the tagline is roughly half its size.
  • Leave a margin of 6–8% on every side — chat apps crop slightly.
  • Use a dark background unless the brand is established light; unfurls are most often read in dark mode.
  • Keep the logo under one quarter of the frame; it is a mark, not a billboard.
  • Keep the typography and colors aligned with the README header and the site.

The connection to the README

The preview and the README are a pair. The README is the long answer; the preview is the glance. The workflow:

  1. Write the one-line description for the README.
  2. Design the preview from the same line and the logo.
  3. Put the file at a stable path, commonly .github/social-preview.png or docs/og.png.
  4. Upload it in repository settings — the file in the repo does not set it automatically.

The developer tool launch guide covers the rest of the launch asset set, including the product hunt images and the demo video.

How it relates to other 1.91:1 images

The GitHub preview, the generic open graph image (1200×630), and the LinkedIn share image (1200×627) are nearly the same family. A 1280×640 master can be adapted, but not reused blindly:

  • The GitHub preview needs the project name visible without a page title.
  • The OG image can lean on the page's own title and description.

The open graph image size guide explains how platforms choose the image.

Common failures

  • The screenshot of the README, scaled down and unreadable.
  • The logo centered with nothing else — the viewer has no idea what the project does.
  • The preview that advertises a different name or an old logo.
  • A file over 1 MB, which GitHub rejects rather than compresses.
  • A 16:9 image uploaded as-is; the ratio is close but not identical, and the edge crop eats margins.
  • A metric that rotted ("1.0 released!" next to a 4.2 version).

Frequently asked questions

Where do I set the GitHub social preview? In the repository, Settings → General → Social preview → Upload an image. The same setting also removes it.

Does the social preview affect SEO? Not directly; it is an open graph-style image. It affects the click-through rate wherever the repo link is shared, and it appears in the repository's own metadata.

Can I use a GIF for the preview? GIFs are accepted within the 1 MB limit, but the animation is rarely visible in unfurls — a clean static PNG is the practical choice.

Can I generate the preview with AI? Yes — the AI asset workflow works here too: feed the one-line description, the logo, and the 1280×640 ratio. A tool such as Neatico generates the preview from that brief in one pass; review it for the safe margins and the small-size readability.

The repo link is shared far more often than it is opened cold. Spend the ten minutes on the preview — 1280×640, under 1 MB, name and one line.