Documentation

RepoCard designs social preview images for GitHub repositories. The social preview is the image shown when someone shares your repository link on X, LinkedIn, Slack, Discord, iMessage and elsewhere.

Quick start

  1. Paste a repository link on the home page.
  2. Pick one of the four concepts and fine-tune it if you like.
  3. Click Download PNG, then follow Add it to GitHub.

Every card is also a stable URL you can embed anywhere:

/card/OWNER/REPO.png
/card/OWNER/REPO.png?variant=2&palette=paper

Add it to GitHub

You need admin access to the repository.

  1. Open the repository on GitHub and click Settings (or go to https://github.com/OWNER/REPO/settings).
  2. On the General page, find Social preview near the top.
  3. Click Edit → Upload an image… and choose the PNG.
  4. That's it. GitHub saves it immediately.

GitHub recommends 1280×640 pixels and under 1 MB, which is exactly what RepoCard produces. To remove a custom image later, use Edit → Remove image.

Why there is no "set it for me" button: GitHub has no public API for the social preview. The API can read it (GraphQL openGraphImageUrl, usesCustomOpenGraphImage) but not change it. The CLI automates the upload in your own browser instead.

Seeing an old image? X, LinkedIn, Slack and Facebook cache link previews for days. Most offer a way to refresh a URL, for example LinkedIn's Post Inspector.

Bulk export

The bulk page lists every public repository of a user or organization with its card, a Settings ↗ link for each, and Download all (ZIP). The ZIP contains one PNG per repository plus an index.html with every settings link.

AI designs asks the model to design each repository (a few seconds each, then cached). Fast uses stored designs if they exist, otherwise deterministic ones, and never calls the model.

CLI

The repocard CLI needs Node.js 20 or later. It renders cards on your machine with the same engine as the website, so it works without any server.

# one repository
npx repocard card vercel/next.js

# every public repository of an account, into ./social-previews
npx repocard bulk your-username

# which repositories already have a custom preview
npx repocard status your-username

Upload to every repository automatically

repocard apply does the upload GitHub doesn't offer an API for. It opens a real browser window, you sign in to GitHub yourself, and it uploads each card through the normal settings page.

# 1. install the browser automation library once
npm install -g playwright && npx playwright install chromium

# 2. dry run: renders cards and shows the plan, uploads nothing
npx repocard apply your-username

# 3. upload
npx repocard apply your-username --yes
OptionDescription
-o, --outOutput file (card) or directory (bulk).
-v, --variantDesign concept 1-4. Default 1.
--layout --palette --font --taglineOverride parts of the design.
--endpointUse a RepoCard server (AI designs) instead of rendering locally. Also REPOCARD_URL.
--forks --archivedInclude forks or archived repositories.
--yesapply: actually upload.
--overwriteapply: replace existing custom previews.
--headlessapply: no window (after signing in once).
--delayapply: milliseconds between repositories. Default 2000.

For AI designs without a server, set LLM_BASE_URL, LLM_API_KEY and LLM_MODEL to any OpenAI-compatible endpoint (Groq, OpenRouter, Gemini, Together, Ollama).

GitHub Action

Keeps a fresh card committed in your repository and can show it as a README banner. Add .github/workflows/social-preview.yml:

name: Social preview
on:
  workflow_dispatch:
  schedule:
    - cron: '0 6 * * 1'
permissions:
  contents: write
jobs:
  card:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nirholas/RepoCard@v1
        with:
          readme-banner: true
InputDefaultDescription
variant1Design concept 1-4.
layout, palette, fontOptional overrides.
path.github/social-preview.pngWhere to write the image.
readme-bannerfalseInsert or update a banner between <!-- repocard:start --> markers.
committrueCommit and push changes.
endpointRepoCard server for AI designs. Without it, cards render on the runner.

The Action can't set the social preview itself (no API). It writes the image and a job summary with the settings link; upload once, or run repocard apply.

HTTP API

No key required. All endpoints are read-only and send CORS headers. Machine-readable spec: /openapi.json.

EndpointReturns
GET /card/{owner}/{repo}.png1280×640 PNG. Errors return a PNG explaining the problem, with the matching status code.
GET /card/{owner}/{repo}.svgThe same card as SVG.
GET /api/v1/cards/{owner}/{repo}The four concepts with specs, PNG/SVG URLs, Markdown, HTML and setup steps.
POST /api/v1/cardsSame, from {"repo": "any GitHub URL", "refresh": true}. refresh asks for new concepts.
GET /api/v1/users/{owner}/reposPublic repositories with card and settings URLs. ?forks=1&archived=1&limit=300.
GET /api/v1/optionsEvery layout, palette, font, background and query parameter.
POST /mcpMCP server for AI agents.

Card parameters

ParameterValues
variant1-4 (default 1)
layoutspotlight, split, editorial, terminal, poster, minimal
palettemidnight, obsidian, aurora, ember, nebula, ocean, forest, terminal, crimson, gold, paper, snow, mint, blush, sand, sky
fontmodern, geometric, technical, editorial, friendly, expressive
backgroundaurora, grid, dots, diagonal, rings, solid
mark, emojiavatar, monogram, emoji, none; emoji=🚀 with mark=emoji
accentHex color without #, adjusted automatically if illegible
title, tagline, chipsText overrides; chips are comma-separated (max 3)
stats=0, owner=0Hide stars/forks/language/license or the owner
mode=fastNever call the AI; use stored or deterministic designs
curl -o card.png "/card/vercel/next.js.png?variant=2"
curl "/api/v1/cards/vercel/next.js"

Images are cached at the edge for several hours. Limits apply to new renders per IP address; cached images are unaffected.

AI agents (MCP)

RepoCard runs a Model Context Protocol server over Streamable HTTP at /mcp. No authentication is needed.

Claude Code

claude mcp add --transport http repocard /mcp

Cursor (.cursor/mcp.json)

{ "mcpServers": { "repocard": { "url": "/mcp" } } }

VS Code (.vscode/mcp.json)

{ "servers": { "repocard": { "type": "http", "url": "/mcp" } } }

Claude Desktop and other stdio clients

{ "mcpServers": { "repocard": { "command": "npx", "args": ["-y", "mcp-remote", "/mcp"] } } }

Tools

ToolWhat it does
create_social_previewDesigns and renders a card. Returns the PNG inline, its URL, the design, and setup steps. Accepts the same overrides as the image URL.
get_design_conceptsAll four concepts with rationale and URLs. refresh asks for new ones.
list_account_cardsEvery public repository of an account with card and settings URLs.
how_to_set_social_previewStep-by-step instructions and automation options.
get_design_optionsThe full design vocabulary.

Agents that prefer plain HTTP can read /llms.txt and /openapi.json.

Design system

The model never writes free-form markup. It picks from a curated vocabulary, and code renders the result:

If the model is unavailable, slow, or returns something unusable, RepoCard falls back to deterministic designs derived from the repository's language and metadata, so a request never fails because of the AI.

Self-hosting

RepoCard is a single Cloudflare Worker with static assets.

Plan requirement: rendering takes roughly 50-300 ms of CPU per new image, so you need the Workers Paid plan (the Free plan allows 10 ms per request). Cached images cost almost nothing.
git clone https://github.com/nirholas/RepoCard && cd RepoCard
npm install
npx wrangler login
npx wrangler kv namespace create DESIGNS   # paste the id into wrangler.jsonc
npx wrangler secret put GITHUB_TOKEN       # fine-grained token, public repositories, read-only
npm run deploy
SettingKindPurpose
AIBindingWorkers AI. Remove to use deterministic designs only.
DESIGNSKV bindingStores designs so each repository keeps a stable look.
RENDER_LIMITER, AI_LIMITERRate limit bindingsPer-IP limits for new renders (60/min) and AI generations (10/min).
GITHUB_TOKENSecretRaises GitHub API limits from 60 to 5,000 requests/hour. Strongly recommended.
AI_PROVIDERVariableworkers-ai (default), openai-compatible, or none.
AI_MODELVariableWorkers AI model. Default @cf/meta/llama-3.3-70b-instruct-fp8-fast.
LLM_BASE_URL, LLM_MODEL, LLM_API_KEYVariables / secretAny OpenAI-compatible endpoint when AI_PROVIDER=openai-compatible.
PUBLIC_URLVariableCanonical origin used in returned URLs. Defaults to the request origin.

Before deploying your own copy, edit wrangler.jsonc: point routes at your domain (or remove them and set "workers_dev": true) and set PUBLIC_URL to match.

Use a custom domain for production: the Workers Cache API, which caches rendered images, doesn't run on *.workers.dev.

Privacy & security

Troubleshooting

"Repository not found"

The repository is private, renamed, or misspelled. RepoCard only supports public repositories.

"Too many requests"

New renders are limited per IP address. Wait a minute; cached cards keep working.

The badge says "Designed from metadata"

The AI was busy or unavailable, so RepoCard used deterministic designs. Click New concepts later to try the AI again.

repocard apply can't find the upload control

GitHub may have changed its settings page. Upload the printed PNG by hand and open an issue.