Repository files navigation

github-statcrab is a Rust-based web server that generates dynamic SVG cards displaying GitHub user statistics and programming language usage. It leverages the GitHub API to fetch user data and presents it in a visually appealing format to be embedded in README files or web pages.

Simple to install & use, easy to customize with various themes and layouts!

Displays the top programming languages used by a GitHub user in a visually appealing card format. You can insert it into your GitHub README with a simple markdown snippet.

Just replace<your-hosted-instance> with the URL of your hosted instance of thegithub-statcrab server andsamgozman with your GitHub username.

[![GitHub Top Languages](https://<your-hosted-instance>/api/langs-card?username=samgozman&layout=horizontal&max_languages=8&theme=dracula&size_weight=0.5&count_weight=0.5)](https://github.com/samgozman/github-statcrab)

[![GitHub Top Languages](https://<your-hosted-instance>/api/langs-card?username=samgozman&layout=vertical&max_languages=8&theme=dracula&size_weight=0.5&count_weight=0.5)](https://github.com/samgozman/github-statcrab)

Can be used to show GitHub user statistics such as total stars, forks, commits, pull requests, issues, and more. You can insert it into your GitHub README with a simple markdown snippet:

[![GitHub Stats for samgozman](https://<your-hosted-instance>/api/stats-card?username=samgozman&theme=monokai)](https://github.com/samgozman/github-statcrab)

You should replace<your-hosted-instance> with the URL of your hosted instance of thegithub-statcrab server andsamgozman with your GitHub username.

Thehide parameter accepts a comma-separated list of the following values:

• stars_count - Total stars received across all repositories
• commits_ytd_count - Total commits made this year
• issues_count - Total issues opened
• pull_requests_count - Total pull requests created
• merge_requests_count - Total merge requests created
• reviews_count - Total pull request reviews performed
• started_discussions_count - Total discussions started
• answered_discussions_count - Total discussions answered

Note: At least 2 statistics must remain visible on the card.

Thegithub-statcrab server supports multiple visual themes for the generated SVG cards. You can customize the appearance of the cards by using thetheme parameter in the API requests.

All available themes and their previews can be found in thethemes readme file.

Adding new themes to thegithub-statcrab is pretty easy. You don't even need to know Rust! You can just open a PR with a new CSS file in theassets/css/themes/ directory. Make sure to follow the existing theme structure and naming conventions. It's the easiest way to contribute!

Github Actions will automatically do the rest for you, including building thethemes readme file page with previews of all themes (yes, it's automated!).

This guide will help you set up and run thegithub-statcrab server.

Get a GitHub Personal Access Token:

• Go toGitHub Settings > Developer settings > Personal access tokens
• Generate new token (classic) withrepo anduser scopes

You will need this token to authenticate with the GitHub API.

You can easily deploy thegithub-statcrab server using template for Railway. Just click the button below to get started:

First of all you need to set up your environment variables. You can do this by creating a.env file in the root directory of the project. You can use the provided.env.example file as a template.

1. Copy the example environment file:

   cp .env.example .env

2. Edit.env and set your GitHub token:

   GITHUB_TOKEN=your_github_personal_access_token_here

3. (optional) add a test GitHub username for local e2e testing:

   TEST_GITHUB_USERNAME=your_github_username

4. (optional) Set up Sentry for error tracking:You can also set optional Sentry configuration for error tracking.

   SENTRY_DSN=your_sentry_dsn_hereSENTRY_ENVIRONMENT=development

5. (optional) Configure cache sizes:You can adjust the cache sizes for user stats and language stats in the.env file.

   # Maximum memory capacity for GitHub API response cache in MiB (default: 32)CACHE_MAX_CAPACITY_MB=32# TTL for user stats cache in seconds (default: 900 = 15 minutes)CACHE_USER_STATS_TTL_SECONDS=900# TTL for user languages cache in seconds (default: 3600 = 1 hour)CACHE_USER_LANGUAGES_TTL_SECONDS=3600

6. (optional) Restrict API access to specific users:You can limit which GitHub usernames are allowed to use the API by setting an allowlist in the.env file.

   # Comma-separated list of GitHub usernames allowed to use the API# Leave empty or unset to allow all users (default: empty)ALLOWED_USERNAMES=user1,user2,user3

You can run the server using Docker. Make sure to replaceyour_github_personal_access_token_here with your actual GitHub Personal Access Token.

docker pull ghcr.io/samgozman/github-statcrab/server:latest  docker run -p 3000:3000 --env-file .env ghcr.io/samgozman/github-statcrab/server:latest

To run the server locally, ensure you have Rust and Cargo installed. You can install them fromrustup.rs.

The server automatically loads environment variables from the.env file:

make run

The server will start onhttp://0.0.0.0:3000 and will automatically read your GitHub token from the.env file.

Run the tests with:

maketest

Why Rust???

Special thanks to@anuraghazra and his amazinggithub-readme-stats for the inspiration!