Generates your own GitHub metrics as an SVG image to put them on your profile page or elsewhere !
See what it looks like below :
Try it now at metrics.lecoq.io with your GitHub username !
A GitHub Action which is run periodically at your convenience which generates and push an SVG image on your personal repository.
Assuming your username is my-github-user, you can embed your metrics in your personal repository's readme like below :
Or with HTML :
<img src="github-metrics.svg" alt="My GitHub metrics">💬 How to setup ?
If you don't know yet or haven't done it yet, create a repository with the same name as your GitHub username.
The README.md of this repository will be displayed on your GitHub user profile like below !
In your account settings, go to Developer settings and select Personal access tokens to create a new token.
You'll need to create a token with the public_repo right so this GitHub Action has enough permissions to push the updated SVG metrics on your personal repository.
Go to the Settings of your personal repository to create a new secret and paste your GitHub token here with the name METRICS_TOKEN.
Go to the Actions of your personal repository and create a new workflow.
Paste the following and don't forget to put your GitHub username.
name: GitHub metrics as SVG image
on:
# Update metrics each 15 minutes. Edit this if you want to increase/decrease frequency
# Note that GitHub image cache (5-15 minutes) still apply so it is useless to set less than this, you're image won't be refreshed
schedule: [{cron: "*/15 * * * *"}]
# Add this if you want to force update each time you commit on master branch
push: {branches: "master"}
jobs:
github-metrics:
runs-on: ubuntu-latest
steps:
- uses: lowlighter/metrics@latest
# This line will prevent this GitHub action from running when it is updated by itself if you enabled trigger on master branch
if: "!contains(github.event.head_commit.message, '[Skip GitHub Action]')"
with:
# Your GitHub token ("public_repo" is required to allow this action to update the metrics SVG image)
token: ${{ secrets.METRICS_TOKEN }}
# Your GitHub user name
user: my-github-user
# Additional options
# ==========================================
# The GitHub token used to commit to your repository (defaults to the same value as "token")
# This can be used to specify the token of a bot account if you use a personal token with advanced permissions
# (which is needed if you want to include metrics of your private repositories, or to enable plugins like traffic)
committer_token: ${{ secrets.METRICS_BOT_TOKEN }}
# Path/filename to use to store generated SVG
filename: github-metrics.svg
# If you own a website and you added it to your GitHub profile,
# You can provide a PageSpeed token to add your site's performance results on the metrics SVG image
# See https://developers.google.com/speed/docs/insights/v5/get-started to obtain a key
plugin_pagespeed: no
pagespeed_token: ${{ secrets.PAGESPEED_TOKEN }}
# Enable repositories lines added/removed count
plugin_lines: no
# Enable repositories traffic (pages views) count
# The provided GitHub token will require "repo" permissions
plugin_traffic: no
# Enable debug logs
debug: no
On each run, a new SVG image will be generated and committed to your repository.
This could virtually increase your commits stats, so it is recommended to pass a bot account token to token instead.
The bot will be able to track metrics of all your public repositories.
If you want to also track your private repositories metrics, you'll need to pass a personal token with repo permissions to token, and use the committer_token parameter to pass the bot account token.
Edit your README.md on your repository and link it your image :
For conveniency, you can use the shared instance available at metrics.lecoq.io.
Assuming your username is my-github-user, you can embed your metrics in your personal repository's readme like below :
💬 Restrictions and fair use
Since GitHub API has rate limitations and to avoid abuse, the shared instance has the following limitations :
- Images are cached for 1 hour
- Your generated metrics won't be updated during this amount of time
- If you enable or disable plugins in url parameters, you'll need to wait for cache expiration before these changes are applied
- A rate limiter prevents new metrics generation when reached, but it does not affect already cached users metrics, including your own
- Most of plugins are not available
- PageSpeed plugin can be enabled by passing
?pagespeed=1, but metrics generation can take up some time
- PageSpeed plugin can be enabled by passing
You should consider deploying your own instance or use GitHub Action if you're planning using this service.
Using your own instance is useful if you do not want to use GitHub Action or allow others users to use your instance.
A GitHub token is required to setup your instance, however since metrics images are not stored on your repositories you do not need to grant any additional permissions to your token, which reduce security issues.
You can restrict which users can generate metrics on your server and apply rate limiting (which is advised or else you'll hit the GitHub API rate limiter).
It is also easier to change query.graphql, style.css and template.svg if you want to gather additional stats, perform esthetical changes or edit the structure of the SVG image.
💬 How to setup ?
You'll need to have a server at your disposal where you can install and configure stuff.
In your account settings, go to Developer settings and select Personal access tokens to create a new token.
As explained above, you do not need to grant additional permissions to the token.
Connect to your server.
You'll need NodeJS (the latter version is better, for reference this was tested on v14.9.0).
Clone the repository
git clone https://github.com/lowlighter/metrics.gitGo inside project and install dependancies :
cd metrics/
npm installCopy settings.example.json to settings.json
cp settings.example.json settings.jsonOpen and edit settings.json to configure your instance.
{
//Your GitHub API token
"token":"****************************************",
//The optionals parameters below allows you to avoid reaching the GitHub API rate limitation
//A set of whitelisted users which can generate metrics on your instance
//Leave empty or undefined to disable
//Defaults to unrestricted
"restricted":["my-github-user"],
//Lifetime of each generated metrics
//If an user's metrics are requested while lifetime is still up, a cached version will be served
//Defaults to 60 minutes
"cached":3600000,
//Maximum simultaneous number of user which can be cached
//When this limit is reached, new users will receive a 503 error
//Defaults to 0 (unlimited)
"maxusers":0,
//Rate limiter
//See https://www.npmjs.com/package/express-rate-limit
//Disabled by default
"ratelimiter":{
"windowMs":60000,
"max":100
},
//Port on which your instance listen
//Defaults to 3000
"port":3000,
//Debug mode
//When enabled, "query.graphql", "style.css" and "template.svg" will be reloaded at each request
//Cache will be disabled
//This is intendend for easier development which allows to see your changes quickly
//Defaults to false
"debug":false,
//Plugins configuration
//Most of plugins are disabled by default
//Enabling them can add additional informations and metrics about you, but increases response time
"plugins":{
//Pagespeed plugin
"pagespeed":{
//Enable or disable this plugin
//When enabled, pass "?pagespeed=1" in url to generate website's performances
"enabled":false,
//Pagespeed token
//See https://developers.google.com/speed/docs/insights/v5/get-started to obtain a key
"token":"****************************************"
},
//Lines plugin
"lines":{
//Enable or disable this plugin
//When enabled, pass "?lines=1" in url to compute total lines added/removed in your repositories by you
"enabled":true
},
//Traffic plugin
"traffic":{
//Enable or disable this plugin
//When enabled, pass "?traffic=1" in url to compute total page views in your repositories in last two weeks
//Note that this requires that the passed GitHub API token requires a push access
"enabled":true
}
}
}Run the following command to start your instance :
npm startOpen your browser and test your instance :
http:https://localhost:3000/my-github-userYou should consider using a service to run your instance. It will allow to restart automatically on crash and on boot.
Create a new file in /etc/systemd/system :
vi /etc/systemd/system/github_metrics.servicePaste the following and edit it with the correct paths :
[Unit]
Description=GitHub metrics
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
WorkingDirectory=/path/to/metrics
ExecStart=/usr/bin/node /path/to/metrics/index.mjs
[Install]
WantedBy=multi-user.target
Reload services, enable it and start it :
systemctl daemon-reload
systemctl enable github_metrics
systemctl start github_metricsCheck if your service is up and running :
systemctl status github_metricsEdit your README.md on your repository and link it your image :
Plugins are additional features that are disabled by default and which may requires additional configuration.
These can provide more informations into your generated metrics, but it could also make it longer to generate, which may not be suitable with a server instance if you're not using caching.
The pagespeed plugin allows you to add your website performances.
These are computed through Google's pagespeed API, which returns the same results as web.dev.
💬 About
To setup this plugin, you'll need an API key that you can generate in the pagespeed API presentation.
The website attached to your GitHub profile will be the one to be audited. It will take about 10 to 15 seconds to generate the results, so it is advised to use this plugin alongside caching system or for automated image generation.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_pagespeed: yes
pagespeed_token: ${{ secrets.PAGESPEED_TOKEN }}Add the following to your settings.json
"plugins":{
"pagespeed":{
"enabled":true,
"token":"****************************************"
}
}And pass ?pagespeed=1 in url when generating metrics.
The lines plugin allows you to add the number of lines of code you added and removed across your repositories.
💬 About
It will consume an additional GitHub request per repository.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_lines: yesAdd the following to your settings.json
"plugins":{
"lines":{
"enabled":true,
}
}And pass ?lines=1 in url when generating metrics.
The traffic plugin allows you to add the number of pages views across your repositories.
💬 About
It will consume an additional GitHub request per repository.
Due to GitHub Rest API limitation, the GitHub token you provide will requires "repo" permissions instead of "public_repo" to allow this plugin accessing traffic informations.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
token: ${{ secrets.METRICS_TOKEN }} # Remember, this must have "repo" permissions for this plugin to work !
plugin_traffic: yesAdd the following to your settings.json
"plugins":{
"traffic":{
"enabled":true,
}
}And pass ?traffic=1 in url when generating metrics.
index.mjscontains the entry points and the settings instancesrc/app.mjscontains the server code which serves renders and apply rate limiting, restrictions, etc.src/metrics.mjscontains metrics renderersrc/query.graphqlis the GraphQL query which is sent to GitHub APIsrc/style.csscontains the style for the generated svg image metricssrc/template.svgcontains the structure of the generated svg image metricssrc/plugins/*contains various additional plugins which can add additional informations in generated metricsaction/index.mjscontains the GitHub action codeaction/dist/index.jscontains compiled the GitHub action codeutils/*contains various utilitaries for build
If you would like to suggest a new feature or find a bug, you can fill an issue describing your problem.
If you're motivated enough, you can submit a pull request to integrate new features or to solve open issues. Read the few sections below to get started with project structure.
If you want to gather additional metrics, update the GraphQL query from src/query.graphql to get additional data from GitHub GraphQL API.
Add additional computations and formatting in src/metrics.mjs.
Raw queried data should be exposed in data.user whereas computed data should be in data.computed.
To use GitHub Rest API or a third-party service instead, create a new plugin in src/plugins.
Plugins should be self-sufficient and re-exported from src/plugins/index.mjs, to be later included in the //Plugins section of src/metrics.mjs.
Data generated should be exposed in data.computed.plugins[plugin] where plugin is your plugin's name.
The SVG template is located in src/template.svg and include the CSS from src/style.css.
It's actually a long JavaScript template string, so you can actually include variables (e.g. `${data.user.name}`) and execute inline code, like ternary conditions (e.g. `${computed.plugins.plugin ? `<div>${computed.plugins.plugin.data}</div>` : ""}`) which are useful for conditional statements.
Most of the time, you won't need to edit these, unless you're integrating features directly tied to them.
Server code is located in src/app.mjs and instantiates an express server app, octokits instances, middlewares (like rate-limiter) and routes.
GitHub action code is located in action/index.mjs and instantiates octokits instances and retrieves action parameters.
It then use directly src/metrics.mjs to generate the SVG image and commit them to user's repository.
To test new features, you'll need to follow the first steps of the Deploying your own instance tutorial.
Basically you create a settings.json containing a test token and debug mode enabled.
You can then start the node with npm start and you'll be able to test how the SVG renders with your editions by opening the server url in your browser.
The following errors code can be encountered if your using a server instance :
403 Forbidden: User is not whitelisted inrestrictedusers list404 Not found: GitHub API did not found the requested user429 Too many requests: Thrown when rate limiter is trigerred500 Internal error: An error ocurred while generating metrics images (logs can be seen if you're the owner of the instance)503 Service unavailable: Maximum user capacity reached, only already cached images can be accessed for now
Below is a list of useful links :
Below is a list of primary dependencies :
- express/express.js and expressjs/compression
- To serve, compute and render a GitHub user's metrics
- nfriedly/express-rate-limit
- To apply rate limiting on server and avoid spams and hitting GitHub API's own rate limit
- octokit/graphql.js and octokit/rest.js
- To perform request to GitHub GraphQL API and GitHub REST API
- ptarjan/node-cache
- To cache generated content
- renanbastos93/image-to-base64
- To generate base64 representation of users' avatars
- svg/svgo
- To optimize generated SVG
- axios/axios
- To make HTTP/S requests
- actions/toolkit and vercel/ncc
- To build the GitHub Action
All icons were ripped across GitHub's site, but still remains the intellectual property of GitHub. See GitHub Logos and Usage for more information.
This project was inspired by the following projects :