GitHub social preview image: size, safe area and design

A GitHub social preview is the image people see when your repository link is shared on X, LinkedIn, Slack, Discord or in a chat. GitHub asks for a PNG, JPG or GIF under 1 MB, at least 640×320 pixels, and recommends 1280×640 for the best display. You upload it in the repository's Settings › General › Social preview, and GitHub then serves it as the repo's Open Graph image.

GitHub social preview size and file rules

Design at 1280×640. It is exactly 2:1, which matches the large card on X and sits close to the 1.91:1 card most other platforms draw. Treat 640×320 as a floor: it looks soft on high density screens.

A designed card with a gradient ground and a few words comes in well under 1 MB as a PNG. If yours does not, it is usually a photo or heavy noise layer; image compression and PNG vs JPEG cover how to bring it down without visible damage.

Where to upload a social preview on GitHub

1. 1

   Open the repository settings

   Go to the repository's main page and click Settings. If the tab is hidden, open the … menu at the end of the tab row.

2. 2

   Find Social preview

   On the General page, scroll to Social preview. Without an image, GitHub shows a generated card with the repo's name, description, a few stats and the owner's avatar.

3. 3

   Upload the image

   Click Edit, then Upload an image…, and choose your 1280×640 PNG.

4. 4

   Test a fresh share

   Paste the repo URL into a new post or chat. If you see the old card, that platform has cached it; see the section on updates below.

To go back to GitHub's generated card, use Edit › Remove image in the same place.

Safe area: what survives every crop

GitHub does not publish a safe area, but the platforms that show your image do crop it. A 2:1 image shown in a 1.91:1 card loses roughly 30 pixels from each side. Some chat apps and mobile layouts crop link images to a square from the centre, which leaves only the middle 640×640. And everything gets small: in a feed the whole card is often a few hundred pixels wide.

• Margins of at least 64 px on every edge, so nothing touches a crop or a rounded corner.
• The project name inside the centre 640×640, so a square crop still says what it is.
• Type tall enough to read small: a name around 96 to 140 px and a line around 40 to 56 px on the 1280×640 canvas.
• Nothing important in the corners, where cards round off and some apps overlay a play or site badge.

What to show on a GitHub social preview

Three things, and nothing more: the project name, one line that says what it does, and a ground that is recognisably yours. The card already shows the URL, so skip the owner, star counts and feature lists. Code screenshots turn to grey noise at card size.

Share one ground across the README banner, docs and social preview so a shared link looks like the project people met on GitHub. Open source project branding covers building that small system around one ground.

Why your GitHub social preview doesn't update

GitHub switches the image on the repository page as soon as you upload it. The old card you still see elsewhere is a cache: X, LinkedIn, Slack, Discord and messaging apps fetch a link's preview once and reuse it, sometimes for days. Old posts keep their old card for good.

• LinkedIn: paste the repo URL into the LinkedIn Post Inspector to fetch it again.
• Everywhere else: share a URL the platform has not seen, such as the repo link with a harmless query on the end (?v=2). It is a new address to the crawler, so it fetches a fresh preview.
• Check GitHub first: open the repo in a private window and confirm Settings shows the new image. If it does, the problem is the platform's cache, not your upload.
• Still blank? The repository may be private; GitHub only shares social previews for public repos.

The same fixes apply to any site's link previews. OG image not showing is the full checklist.

How the social preview relates to OG images

The social preview is an Open Graph image. GitHub writes it into the repo page's og:image tag, with a large card setting for X, so every platform reads it the same way it reads yours. You cannot edit those tags on github.com, which is why the upload exists.

<!-- Roughly what GitHub serves in the head of a public repo page -->
<meta property="og:title" content="tidewater-dev/tidewater" />
<meta property="og:description" content="Fast diffing for large JSON files." />
<meta property="og:image" content="https://repository-images.githubusercontent.com/..." />
<meta property="og:url" content="https://github.com/tidewater-dev/tidewater" />
<meta name="twitter:card" content="summary_large_image" />

For your project's own website, you set these tags yourself, usually with a 1200×630 image. Design the two as a pair: same ground, same name, same line, at 1280×640 for GitHub and 1200×630 for the site. With good margins, one layout fits both. OG image size and Open Graph tags cover the site side, and dynamic OG images shows how to generate one per docs page.

Make a GitHub social preview in Gradiently

In the Studio, start a design at a custom size of 1280×640 and pick a Mark as the ground. Set the project name and one line; the Mark keeps its calmest region behind the words and Auto ink picks light or dark type from its palette, so it reads in both light and dark apps. Export as PNG and upload it in Social preview. For the matching site card, add the built-in Link preview (Open Graph) 1200×630 size to the same design so both share one ground.