GitHub Repo Banner

URL-based repository banners. Think shields.io, but for headers. ✨

I believe every repository deserves to look beautiful. Your code is art, your projects deserve stunning visuals to match. But design tools steal hours you don't have. So I built a service that generates gorgeous banners through simple URL parameters. Instant, customizable, and no design tools required. Because great projects deserve great repository banners.

🚁 Deploy Your Own

When you deploy your own copy, you're directly supporting this project! 💖

✨ Features

🎨 Hex-Based Customization - Full control with hex codes for backgrounds, gradients, and text colors
🌈 Gradient Support - Create custom gradients using bg=HEX1-HEX2 format
💧 Opacity Control - 8-digit hex codes with alpha channel (RRGGBBAA)
🔤 Google Fonts Integration - Use any font from Google Fonts for custom typography
😀 Native Emoji - Full emoji support with proper rendering
🎯 Simple Icons Support - Use 3000+ brand icons with ![slug] syntax (e.g., ![github], ![react])
📥 SVG & PNG Download - Download banners as SVG or PNG directly from the UI
⚡ Lightning Fast - Built with Hono framework for optimal performance
🔒 Secure - Input sanitization and validation
🚀 Edge-Ready - Deploy to modern platforms like Railway

🚀 Quick Start

Use the Hosted Service

Visit ghrb.waren.build to create your banner using the interactive UI.

Self-Hosting

git clone https://github.com/warengonzaga/github-repo-banner.git
cd github-repo-banner
pnpm install
pnpm dev

📖 Usage Examples

Basic Examples

Gradient Background

https://ghrb.waren.build/banner?header=Vibe+Coding%F0%9F%9A%80&bg=ec4899-3b82f6&color=ffffff

Solid Color with Subheader

https://ghrb.waren.build/banner?header=OSSPH&subheader=Leading+Open+Source+Software+Community+in+the+Philippines&bg=E7F9FF-90C4E8&color=0060A0

With Emojis & Custom Fonts

https://ghrb.waren.build/banner?header=%F0%9F%A6%9EOpenClaw&subheader=Your+own+personal+AI+assistant.&bg=fee2e2&color=bb2c2c&support=true

With Brand Icons (Simple Icons)

https://ghrb.waren.build/banner?header=![github]+Hello+World&bg=1a1a1a-4a4a4a&color=ffffff
https://ghrb.waren.build/banner?header=![react]+![typescript]+Modern+Stack&bg=14b8a6-06b6d4&color=ffffff

Use ![slug] syntax to embed any icon from Simple Icons. Over 3000+ brand icons available! Icons automatically adapt to your text color.

Transparent/Opacity

https://ghrb.waren.build/banner?header=Transparent&bg=00000000&color=ffffff
https://ghrb.waren.build/banner?header=Semi-Transparent&bg=ffffff80&color=000000

🌟 Who Uses This

Projects and organizations using GitHub Repo Banner:

gogcli by steipete - Google in your terminal
summarize by steipete - Fast summaries from URLs, files, and media.
BetterGov PH - Making government services better for Filipinos

🔒 Privacy & Transparency

Privacy by default. This service does NOT track anything by default. If you're using the hosted version at ghrb.waren.build, stats tracking status is available at /health.

What We Track (When Enabled)

✅ Repository names only - GitHub repository URLs from browser Referer headers
✅ Public data only - Already publicly visible on GitHub

What We Log (Always)

📊 User actions - Button clicks (Copy Markdown, Download SVG, etc.) and the banner URL generated
🎨 Banner content - Text and styling parameters (publicly displayed content only)
💡 Purpose - Understand feature usage and popular banner styles to improve the service

Note: All logs are ephemeral (console only, not stored in database). The content you generate is meant to be publicly displayed on GitHub, so logging helps improve the service without violating privacy.

What We DON'T Track

❌ No IP addresses
❌ No personal information
❌ No user identities
❌ No analytics or behavioral data
❌ No cookies or tracking pixels
❌ No session data or persistent storage

Why Track (When Enabled)

Understanding which repositories use this service helps:

Gauge community value and impact
Make informed maintenance decisions
Justify resources for this free service

Your Data Rights

Full transparency: View tracked data at /stats (when enabled)
Opt-out: Self-host with stats disabled (default)
Open source: Review tracking code in this repository

Self-Hosting Privacy

Self-hosted instances have stats disabled by default. To enable (optional):

Set ENABLE_STATS=true in your .env
Add Redis service to your Railway project
See Railway Deployment below

🚂 Railway Deployment

Basic Deployment (Stats Disabled - Default)

No additional configuration needed. The service runs without stats tracking.

With Stats Tracking (Optional)

If you want to track which repositories use your instance:

Deploy the service using the button above
Add Redis service in Railway dashboard:
- Click "New" → "Database" → "Add Redis"
- Railway automatically sets REDIS_URL
Enable stats in your service variables:
- Go to your service settings
- Add variable: ENABLE_STATS=true
Redeploy your service

Accessing Stats:

View at: https://your-service.railway.app/stats
Health check includes stats status: https://your-service.railway.app/health

Cost Note: Redis on Railway has a free tier, then usage-based pricing. Stats tracking is lightweight and should stay within free limits for moderate traffic.

🔌 API Reference

`GET /banner`

Generate a custom SVG banner.

Parameters

Parameter	Type	Required	Default	Description
`header`	string	No	"Hello World"	Main text (supports emojis and icons)
`subheader`	string	No	-	Optional subtitle text
`bg`	string	No	`1a1a1a-4a4a4a`	Background color in hex format
`color`	string	No	`ffffff`	Header text color (hex without #)
`subheadercolor`	string	No	Same as `color`	Subheader text color
`headerfont`	string	No	-	Google Fonts family name for header (e.g., "Roboto")
`subheaderfont`	string	No	-	Google Fonts family name for subheader (e.g., "Playfair Display")
`support`	boolean	No	`false`	Show support watermark
`watermarkpos`	string	No	`bottom-right`	Watermark position: `top-left`, `top-right`, `bottom-left`, `bottom-right`

Background Format

Format	Example	Description
Gradient	`HEX1-HEX2`	`1a1a1a-4a4a4a` (left to right)
Solid	`HEX`	`ffffff` (single color)
Transparent	`00000000`	Fully transparent
With Opacity	`RRGGBBAA`	`ffffff80` (50% opacity)

Response

Content-Type: image/svg+xml
Cache-Control: public, max-age=86400 (production)
Size: 1280×304px

`GET /`

Interactive banner generator UI with live preview.

`GET /health`

Health check endpoint for monitoring and stats status.

Response (stats disabled):

{
  "status": "ok",
  "timestamp": "2026-02-01T00:00:00.000Z",
  "stats": {
    "enabled": false
  }
}

Response (stats enabled):

{
  "status": "ok",
  "timestamp": "2026-02-01T00:00:00.000Z",
  "stats": {
    "enabled": true,
    "endpoint": "/stats"
  }
}

`GET /stats`

View repository tracking statistics (when enabled).

Response (stats disabled):

{
  "enabled": false,
  "message": "Stats tracking is disabled"
}

Response (stats enabled):

{
  "enabled": true,
  "totalRepositories": 42,
  "repositories": ["owner/repo1", "owner/repo2"],
  "note": "Only tracking public GitHub repositories using this service"
}

🎨 Color Presets

The UI includes presets for quick access:

Gradients

Name	Background	Text Color
Midnight	`1a1a1a-4a4a4a`	`ffffff`
Vibe	`ec4899-3b82f6`	`ffffff`
Ocean	`14b8a6-06b6d4`	`ffffff`
Railway 🆕	`431586-9231A8`	`ffffff`
Cloudflare 🆕	`F38020-FBAB41`	`ffffff`
Waren 🆕	`013B84-016EEA`	`ffffff`
OSSPH	`E7F9FF-90C4E8`	`0060A0`

Solid Colors

Name	Background	Text Color
Sky	`87ceeb`	`1e3a8a`
Molty	`fee2e2`	`bb2c2c`
Claude	`fde8e3`	`de7356`
GPT	`10a37f`	`ffffff`
Minimal	`f3f4f6`	`1f2937`

Special

Name	Background	Text Color	Preview
Transparent	`00000000`	`ffffff`

Tip: Create any custom gradient or color using hex codes directly in the URL.

🛠️ Development

Tech Stack

Runtime: Node.js • Framework: Hono • Language: TypeScript • Build: tsup • Package Manager: pnpm

Commands

pnpm dev      # Development with hot-reload
pnpm build    # Production build
pnpm start    # Start production server

Environment Variables

PORT=3000              # Server port
NODE_ENV=development   # Environment mode

# Stats Tracking (disabled by default - privacy-first)
ENABLE_STATS=false     # Set to 'true' to enable repository tracking
REDIS_URL=             # Required only if ENABLE_STATS=true

See .example.env for complete documentation.

Security

Input sanitization (XSS prevention)
Hex color validation
Header length limits
No external dependencies

🤝 Contributing

Contributions are welcome! For major changes, open an issue first.

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit with Clean Commit convention
Push and open a Pull Request

📄 License

MIT License - see LICENSE file.

👨‍💻 Author

Waren Gonzaga • GitHub • Website

💻💖☕ by Waren Gonzaga | YHWH 🙏

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.github		.github
src		src
.example.env		.example.env
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Uh oh!

License

warengonzaga/github-repo-banner

Folders and files

Latest commit

History

Repository files navigation

GitHub Repo Banner

🚁 Deploy Your Own

✨ Features

🚀 Quick Start

Use the Hosted Service

Self-Hosting

📖 Usage Examples

Basic Examples

🌟 Who Uses This

🔒 Privacy & Transparency

What We Track (When Enabled)

What We Log (Always)

What We DON'T Track

Why Track (When Enabled)

Your Data Rights

Self-Hosting Privacy

🚂 Railway Deployment

Basic Deployment (Stats Disabled - Default)

With Stats Tracking (Optional)

🔌 API Reference

GET /banner

Parameters

Background Format

Response

GET /

GET /health

GET /stats

🎨 Color Presets

Gradients

Solid Colors

Special

🛠️ Development

Tech Stack

Commands

Environment Variables

Security

🤝 Contributing

📄 License

👨‍💻 Author

About

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases 1

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors 4

Uh oh!

Languages

`GET /banner`

`GET /`

`GET /health`

`GET /stats`

Packages