Prepare the right file
GitHub’s current guidance accepts PNG, JPG or GIF files under 1 MB. It recommends at least 640 × 320 pixels, with 1280 × 640 for the best display. Start with the larger 2:1 canvas, then check readability at a much smaller size.
For a fictional CSV validator, a clear layout could show the project name, “Check CSV files before import”, and a simple input-to-error example. Avoid squeezing an entire terminal session into a thumbnail. Keep important text away from the edges in case a sharing surface crops the image.
Upload and check the shared link
Open the repository Settings, locate Social preview, choose Edit and upload the image. Share the public repository URL in the destination where your audience will see it. Check the result there; upload success does not guarantee every platform immediately replaces a cached preview.
- Confirm that the image belongs to the repository you are sharing.
- Check the file format, pixel dimensions and file size before upload.
- Use readable contrast; inspect transparent artwork on light and dark backgrounds.
- If the image is stale, confirm the saved repository setting and investigate the destination platform’s cache.
Keep the preview consistent with the project
Use the same project name and purpose in the image, README and release announcement. If a screenshot shows an experimental feature, label it or use a stable workflow instead. Do not add fabricated Star counts, customer logos or performance claims.
Revisit the image when the project’s central use case changes. A preview is a communication asset, not a separate guarantee of ranking, click-through rate or GitHub Stars.
Common questions
Is this the same as the repository owner’s avatar?
No. The owner avatar identifies the account. A custom repository social preview represents a particular project when its link is shared.
Can the preview use a transparent background?
GitHub supports PNG transparency. Check contrast on different backgrounds; a solid background is a practical choice when the destination appearance is uncertain.
Why do I still see the old preview after uploading?
First verify that the new image is saved on the correct repository. Sharing platforms may cache previews; their refresh behavior is separate from the repository setting.