Laying out the card…
Size1280 × 640
ThemeDark
Weight—
Limit0% used
The image GitHub shows when your repository is linked anywhere else — a tweet, a Slack channel, a newsletter. Left unset, the link unfurls as a generic grey card with an octocat on it, which is the difference between a project that looks maintained and one that does not. GitHub rejects anything over a megabyte outright, so the file size is shown against that limit while you are still designing.
Step by step
01Fill in the repository
Owner, name, and the repository's own description. Using the real description rather than a marketing line keeps the card and the repository page saying the same thing.
02Set the language
The coloured dot beside a repository is the most recognisable thing on GitHub. These are the real linguist colours, so a reader identifies the card as a repository before reading a word of it.
03Decide about the counts
Star and fork numbers make a card look alive, and they are wrong the week after you upload it. Leave them off for anything you will not revisit.
04Watch the megabyte
The bar shows the encoded size against GitHub's hard limit. A gradient card as PNG can pass it; the same card as JPEG rarely comes close, and no viewer can tell the difference at feed size.
Worked example
GitHub refuses an upload above 1 MB and does not say by how much. The cause is almost always the format rather than the design.
Given
The same card, encoded two ways
PNG lossless every gradient step stored exactly
JPEG quality 0.9 tonal change is what JPEG is built for
A gradient is the worst case for PNG and the best case for
JPEG, so the gap between them is at its widest here.PNG stores a gradient as thousands of distinct values it is not allowed to approximate, which is exactly what it is worst at. JPEG approximates smooth tonal change by design, and at quality 0.9 the loss is invisible at any size a link preview is drawn. Reach for PNG only when the background is flat colour, where the gap narrows and the crisper type is worth having.
Before you upload it
The default is a grey card with an octocat
A repository with no social preview set unfurls as a generic placeholder wherever it is shared. It is the single cheapest signal that a project is maintained, and it is set once and never touched again.
1280 × 640, and it is the same 1.91:1 as everywhere else
GitHub asks for 1280 × 640 for high-resolution displays, and accepts down to 640 × 320 at the same ratio. Because the shape matches the Open Graph standard, the card also works when the link is pasted into Slack or a chat.
One megabyte is a hard limit
GitHub rejects a larger file rather than compressing it, and the error does not tell you the size. This is the most common reason a carefully made preview never gets uploaded, and switching format almost always fixes it.
Keep the content in the middle
The centre 1000 × 500 is what survives everywhere the card is reused. GitHub itself shows the whole image, but the same file pasted into a chat client is subject to that client's crop.
Star counts go stale
A number baked into an image is a claim frozen on the day you exported it. On a repository that is still growing, an old count reads worse than none at all — which is why the counts here are optional rather than assumed.
The repository name has to survive a small preview
The card is authored at 1280 pixels and drawn at a fraction of that in a timeline. The name is the one element that must stay readable at the narrow end, which puts the practical floor around 64 pixels as authored.
The judgement call
A social preview is read in about a second. Each element has to earn its place.
The repository name
Always
It is the one thing a reader needs, and it should be the largest element by a clear margin.
The one-line description
Always
Two clamped lines answer 'what is this' before anyone clicks. Reuse the repository's own description.
The language dot
Usually
It identifies the card as a repository instantly, and tells a developer whether it is relevant to them.
Star and fork counts
Only if you will update it
They date. A stale count on a growing project reads worse than showing nothing.
The owner avatar
For an organisation
A recognised logo adds trust. A personal avatar mostly adds noise at preview size.
A screenshot of the project
Rarely
UI detail is illegible at the size a preview is drawn, and it pushes the file toward the 1 MB limit.
Reference
FAQ
1280 × 640 pixels, which is the size GitHub recommends for high-resolution displays. The ratio is 1.91:1 and images down to 640 × 320 are accepted at that same shape. The file must be a PNG or JPEG under 1 MB — GitHub rejects anything larger rather than compressing it.
Open the repository's Settings tab and scroll to the 'Social preview' section, roughly a third of the way down the General page, then use Edit to upload the image. It applies to that repository only, so each one needs its own — the card is shown wherever the repository link is unfurled.
Almost always because it is over the 1 MB limit, which GitHub enforces without telling you the file's size. A card with a gradient background encoded as PNG is the usual culprit; re-encoding the same design as JPEG typically brings it far under the limit with no visible difference at preview size.
Only if you will re-export the card as the numbers change. A star count baked into an image is frozen on the day it was made, and a stale figure on a growing project reads worse than showing no numbers at all. For a repository you will not revisit, leave the counts off.
Yes. GitHub's 1280 × 640 is the same 1.91:1 shape as the Open Graph standard, so the same file unfurls correctly in Slack, Discord, X and iMessage. Keep the important content within the centre 1000 × 500 so it survives the slightly different crops those clients apply.
No. The Tinapps GitHub social preview generator lays the card out with satori in your browser and never contacts GitHub or any other service — the owner, repository name and description stay on your machine, which matters when the repository is still private.
The card is laid out and encoded entirely in your browser. The repository name, description, and any avatar you add are never uploaded — not to GitHub, and not here.
Keep going
OG image generator
The same job for a web page, at 1200 × 630.
Code snippet image
Turn a snippet from the README into a shareable picture.
Image compressor
Squeeze a card that is still over the megabyte after switching format.
Favicon generator
The project's other identity asset, from the same mark.