Generate your metrics that you can embed everywhere, including your GitHub profile readme !
But there's more with plugins and templates !
Classic template | Terminal template |
---|---|
|
|
Repository template A special template to embed on any repository readme ! |
|
|
|
More to come soon ! |
Try it now at metrics.lecoq.io with your GitHub username !
Because some plugins require additional configuration and setup, some of them are not available at metrics.lecoq.io. For a fully-featured experience, consider using this as a GitHub Action instead !
Setup a GitHub Action which runs periodically and pushes your generated metrics image on your repository. See all supported options in action.yml.
Assuming your username is my-github-user
, you can then embed your metrics in your repository readme like below :
![Metrics](https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg)
๐ฌ How to setup ?
Create a repository with the same name as your GitHub username if it's not already done.
The README.md
of it will be displayed on your user profile :
From the Developer settings
of your account settings, select Personal access tokens
to create a new token.
No additional scopes are needed, unless you want to include your private repositories metrics.
With a scope-less token, you can still display private contributions by enabling Include private contributions on my profile
in your account settings :
Some plugins also require additional scopes, which is indicated in their respective documentation.
In case your token does not have the required scope (and plugins_errors_fatal
is not enabled), it will be directly notified in the plugin render like below :
Go to the Settings
of your personal repository to create a new secret and paste your freshly generated GitHub token there.
Create a new workflow from the Actions
tab of your personal repository and paste the following :
name: Metrics
on:
# Schedule updates
schedule: [{cron: "0 * * * *"}]
push: {branches: "master"}
jobs:
github-metrics:
runs-on: ubuntu-latest
steps:
# See action.yml for all options
- uses: lowlighter/metrics@latest
with:
# Your GitHub token
token: ${{ secrets.METRICS_TOKEN }}
# GITHUB_TOKEN is a special auto-generated token restricted to current repository, which is used to push files in it
committer_token: ${{ secrets.GITHUB_TOKEN }}
See all supported options in action.yml.
When using a token with additional permissions, it is advised to fork this repository to minimize security risks :
- uses: my-github-username/metrics@latest
In this case, consider watching new releases of this repository to stay up-to-date and enjoy latest features !
It is possible to use @master
instead of @latest
to use new features before their official release.
Breaking changes may occur occasionally on @master
, which could result in your metrics not being generated temporarily.
A new metrics image will be generated and committed to your repository on each run.
Check out this workflow file which generates metrics daily.
Note that most of steps presented there are illustrative examples for this readme and are actually not needed to generate your own metrics.
Edit your repository readme and add your metrics image :
![Metrics](https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg)
For conveniency, you can use the shared instance available at metrics.lecoq.io without any additional setup.
Assuming your username is my-github-user
, you can embed your metrics in your repository readme like below :
![Metrics](https://metrics.lecoq.io/my-github-user)
Visit metrics.lecoq.io for more informations.
๐ฌ Restrictions and fair use
Since GitHub API has rate limitations, the shared instance has a few limitations :
- Images are cached for 1 hour
- Your generated metrics won't be updated during this amount of time when queried
- A rate limiter is enabled, although it won't affect already cached users metrics
- Plugins which consume additional requests, or require additional token scopes are disabled
If you're appreciating this project, consider using it as a GitHub Action instead.
It is possible to setup your own instance if you don't want to use GitHub Actions or if you want to allow others users on your instance.
When sharing an instance, it is advised to restrict the number of users which can use it through the rate limiter or the access list, to avoid reaching the requests limit of GitHub APIs.
See all supported options in settings.example.json.
๐ฌ How to setup ?
You will need a server where you can setup and run a NodeJS application.
From the Developer settings
of your account settings, select Personal access tokens
to create a new token.
No additional scopes are needed.
Connect to server and ensure NodeJS is installed (see tested version in workflow).
Run the following commands to clone this repository, install dependencies and copy configuration example file :
git clone https://github.com/lowlighter/metrics.git
cd metrics/
npm install --only=prod
cp settings.example.json settings.json
Edit settings.json
to configure your instance.
{
//See settings.example.json for all options
//GitHub API token
"token":"****************************************"
}
See all supported options in settings.example.json.
Run the following command to start your instance once you've finished configuring it :
npm start
From your browser, you should be able to access your web instance on the port you provided in setting.json
.
Edit your repository readme and add your metrics image from your server domain :
![Metrics](https://my-personal-domain.com/my-github-user)
To ensure that your instance will be restarted in case of reboots or crashs, you should setup it as a service. This is described below for linux-like systems which supports systemd.
Create a new service file /etc/systemd/system/github_metrics.service
and paste the following after editing paths inside :
[Unit]
Description=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, start it and check if it is up and running :
systemctl daemon-reload
systemctl enable github_metrics
systemctl start github_metrics
systemctl status github_metrics
โ ๏ธ HTTP errors code
The following errors code can be encountered on a web instance :
Error code | Description |
---|---|
400 Bad request |
Invalid query (e.g. unsupported template) |
403 Forbidden |
User not allowed in restricted users list |
404 Not found |
GitHub API did not found the requested user |
429 Too many requests |
Thrown when rate limiter is trigerred |
500 Internal error |
Server error while generating metrics images (check logs for more details) |
503 Service unavailable |
Maximum user capacity reached, only cached images can be accessed for now |
๐ HTTP parameters
Generated metrics images from a web instance can be configured through url parameters.
Base content is enabled by default, but passing ?base=0
will disable all base content.
You can choose to selectively enable or disable a specific <section>
with ?base.<section>=<1|0>
.
For example, to opt-out from activity
, community
and metadata
, append ?base.activity=0&base.community=0&base.metadata=0
to your metrics url.
Plugins are disabled by default, but passing ?<plugin>=1
will enable a specific <plugin>
.
Plugin options can be passed with ?<plugin>.<option>=<value>
.
For example, to enable music
plugin and configure music
plugin, you could append the following to your metrics url : ?music=1&music.provider=spotify&music.mode=recent&music.limit=4
.
Basically, most of action.yml options can actually be used by web instance, with plugin_
prefix dropped, and .
instead of _
.
Templates allows you to change the general appearance of your metrics images. Some metrics may be displayed differently, and all plugins may not be supported or behave the same from one template to another.
Consider trying them at metrics.lecoq.io !
Used template defaults to the classic
one.
Template\Plugin | ๐๏ธ | โฑ๏ธ | ๐ | ๐ผ | ๐ท๏ธ | ๐๏ธ | ๐ | ๐๏ธ | ๐จโ๐ป | ๐งฎ | ๐ค | โ๏ธ | ๐ก | ๐ซ | ๐ | โจ |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Classic | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ | โ๏ธ |
Terminal | โ๏ธP | โ๏ธ | โ | โ | โ๏ธ | โ๏ธ | โ | โ | โ๏ธ | โ๏ธ | โ | โ | โ | โ๏ธ | โ | โ |
RepositoryR | โ๏ธ | โ | โ | โ | โ | โ๏ธ | โ | โ๏ธ | โ๏ธ | โ๏ธ | โ | โ | โ | โ | โ | โ๏ธ |
Legend
- P : Partial support (Hover cell for more informations)
- M : Feature is not released yet but is available on
@master
- N : Feature is already released, but new ones are available on
@master
- R : Repository template (all plugins content will be restricted to related repository)
๐ฌ Using repository template
To use repository
template, you'll need to provide a repository name in query
option.
If repository owner is different from token
owner, use user
option to specify it.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
template: repository
user: "repository-owner"
query: '{"repo":"repository-name"}'
Plugins are features which can provide additional metrics and features. In return, they may require additional configuration and consume additional API requests.
Generated metrics contains a few sections that are enabled by default, such as recent activity, community stats and repositories stats. This can be configured by explicitely opt-out from them.
๐ฌ About
By default, generated metrics contains the following sections :
header
, which usually contains your username, your two-week commits calendars and a few additional dataactivity
, which contains your recent activity (commits, pull requests, issues, etc.)community
, which contains your community stats (following, sponsors, organizations, etc.)repositories
, which contains your repositories stats (license, forks, stars, etc.)metadata
, which contains informations about generated metrics
You can explicitely opt-out from them, which can be useful if you only want to keep a few sections or to use a plugin as standalone.
For example, to keep only header
and repositories
sections, add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
base: "header, repositories" # opt-out from "activity", "community" and "metadata"
By default, the community
section only counts public organizations memberships.
You can change your membership visibility in the People
tab of your organization :
To include private organizations memberships, you'll need to add the read:org
scope to your personal token.
The pagespeed plugin adds the performances of the website attached mentioned on your account :
These are computed through Google's PageSpeed API, which yields the same results as web.dev.
๐ฌ About
Although not mandatory, you can generate an API key for PageSpeed API here to avoid 429 HTTP errors.
The website attached to the GitHub profile will be the one to be audited. Expect 10 to 30 seconds to generate the results.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_pagespeed: yes
plugin_pagespeed_token: ${{ secrets.PAGESPEED_TOKEN }}
You can display a detailed report along with scores :
See performance scoring and score calculator for more informations about how PageSpeed compute these statistics.
Add the following to your workflow instead :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_pagespeed: yes
plugin_pagespeed_detailed: yes
plugin_pagespeed_token: ${{ secrets.PAGESPEED_TOKEN }}
You can also display the screenshot taken by PageSpeed API :
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_pagespeed_screenshot: yes
It is possible to audit a different website from the one linked to your GitHub account by using plugin_pagespeed_url
option.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_pagespeed_url: https://********
The isocalendar plugin displays an isometric view of your commits calendar, along with a few stats like current streak and commit average per day.
๐ฌ About
It will consume two additional GitHub requests.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_isocalendar: yes
Use the following instead to display a full-year instead :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_isocalendar: yes
plugin_isocalendar_duration: full-year
The music plugin can work in the following modes :
Select randomly a few tracks from a given playlist so you can display your favorite tracks to your visitors.
๐ฌ About
Select a music provider below for instructions.
Apple Music
Extract the embed url of the playlist you want to share.
To do so, connect to music.apple.com and select the playlist you want to share.
From ...
menu, select Share
and Copy embed code
.
Extract the source link from the code pasted in your clipboard :
<iframe allow="" frameborder="" height="" style="" sandbox="" src="https://embed.music.apple.com/**/playlist/********"></iframe>
Finish the plugin setup by adding the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_music: yes
plugin_music_provider: apple
plugin_music_mode: playlist
plugin_music_playlist: https://******** # Extracted source link
plugin_music_limit: 4 # Set the number of tracks you want to display
Spotify
Extract the embed url of the playlist you want to share.
To do so, Open Spotify and select the playlist you want to share.
From ...
menu, select Share
and Copy embed code
.
Extract the source link from the code pasted in your clipboard :
<iframe src="https://open.spotify.com/embed/playlist/********" width="" height="" frameborder="0" allowtransparency="" allow=""></iframe>
Finish the plugin setup by adding the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_music: yes
plugin_music_provider: spotify
plugin_music_mode: playlist
plugin_music_playlist: https://******** # Extracted source link
plugin_music_limit: 4
Display tracks you played recently.
๐ฌ About
Select a music provider below for additional instructions.
Apple Music
This mode is not supported for now.
I tried to find a way with smart playlists, shortcuts and other stuff but could not figure a workaround to do it without paying the 99$ fee for developper program.
So unfortunately this isn't available for now.
Spotify
Spotify does not have personal tokens, so it makes the process a bit longer because you're required to follow the authorization workflow... Follow the instructions below for a TL;DR to obtain a refresh_token
.
Sign-in to the developer dashboard and create a new app.
Keep your client_id
and client_secret
and let this tab open for now.
Open the settings and add a new Redirect url. Normally it is used to setup callbacks for apps, but just put https://localhost
insteadd (it is mandatory as per the authorization guide, even if not used).
Forge the authorization url with your client_id
and the encoded redirect_uri
you whitelisted, and access it from your browser :
https://accounts.spotify.com/authorize?client_id=********&response_type=code&scope=user-read-recently-played&redirect_uri=https://localhost
When prompted, authorize your application.
Once redirected to redirect_uri
, extract the generated authorization code
from your url bar.
Go back to your developer dashboard tab, and open the web console of your browser to paste the following JavaScript code, with your own client_id
, client_secret
, authorization code
and redirect_uri
.
(async () => {
console.log(await (await fetch("https://accounts.spotify.com/api/token", {
method:"POST",
headers:{"Content-Type":"application/x-www-form-urlencoded"},
body:new URLSearchParams({
grant_type:"authorization_code",
redirect_uri:"https://localhost",
client_id:"********",
client_secret:"********",
code:"********",
})
})).json())
})()
It should return a JSON response with the following content :
{
"access_token":"********",
"expires_in": 3600,
"scope":"user-read-recently-played",
"token_type":"Bearer",
"refresh_token":"********"
}
With your client_id
, client_secret
and refresh_token
you can finish the plugin setup by adding the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_music: yes
plugin_music_provider: spotify
plugin_music_token: "${{ secrets.SPOTIFY_CLIENT_ID }}, ${{ secrets.SPOTIFY_CLIENT_SECRET }}, ${{ secrets.SPOTIFY_REFRESH_TOKEN }}"
plugin_music_mode: recent
plugin_music_limit: 4
The languages plugin displays which programming languages you use the most across all your repositories.
๐ฌ About
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_languages: yes
plugin_languages_ignored: "" # List of comma separated languages to ignore
plugin_languages_skipped: "" # List of comma separated repositories to skip
The follow-up plugin displays the ratio of opened/closed issues and the ratio of opened/merged pull requests across all your repositories, which shows if they're well-maintened or not.
๐ฌ About
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_followup: yes
The topics plugin displays your starred topics. Check out GitHub topics to search interesting topics.
๐ฌ About
This uses puppeteer to navigate through your starred topics page.
You can choose to display and order topics by :
- Most
stars
- Recent
activity
- Recently
starred
by you random
ly
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_topics: yes
plugin_topics_sort: stars
plugin_topics_limit: 15
It is possible to display starred topics as Mastered and known technologies
instead :
Add the following to your workflow instead :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_topics: yes
plugin_topics_mode: mastered
plugin_topics_limit: 0
โ ๏ธ This plugin requires a personal token with public_repo scope.
The projects plugin displays the progress of your profile projects.
๐ฌ About
It will consume an additional GitHub request.
Because of GitHub REST API limitation, provided token requires public_repo
scope to access projects informations.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_projects: yes
plugin_projects_limit: 4
Note that by default, profile projects have progress tracking disabled.
To enable it, open the โก Menu
and edit the project to opt-in to Track project progress
(it can be a bit confusing since it's actually not in the project settings).
It is possible to display projects related to repositories along with personal projects.
To do so, open your repository project and retrieve the last url endpoint, in the format :user/:repository/projects/:project_id
(for example, lowlighter/metrics/projects/1
) and add it in the plugin_projects_repositories
option. Enable Track project progress
in the project settings to display a progress bar in generated metrics.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_projects: yes
plugin_projects_repositories: :user/:repository1/projects/:project_id, :user/:repository2/projects/:project_id, ...
The lines of code plugin displays the number of lines of code you added and removed across all of 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: yes
โ ๏ธ This plugin requires a personal token with repo scope.
The repositories traffic plugin displays the number of pages views across your repositories.
๐ฌ About
It will consume an additional GitHub request per repository.
Because of GitHub REST API limitation, provided token requires full repo
scope to access traffic informations.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# Token with "repo" scope
token: ${{ secrets.METRICS_TOKEN }}
# ... other options
plugin_traffic: yes
The recent tweets plugin displays your latest tweets of the twitter attached mentioned on your account :
๐ฌ About
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_tweets: yes
plugin_tweets_token: ${{ secrets.TWITTER_TOKEN }}
It is possible to use a different twitter username from the one linked to your GitHub account by using plugin_tweets_user
option.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_tweets_user: ********
๐ฌ Obtaining a twitter token
To get a twitter token, you'll need to apply to the developer program. It's a bit tedious, but it seems that requests are approved quite quickly.
Create an app from your developer dashboard and register your bearer token in your repository secrets.
The recent posts plugin displays recent articles you wrote on an external source, like dev.to.
๐ฌ About
Supported sources are :
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_posts: yes
plugin_posts_source: ********
It is possible to use a different username from your GitHub account by using plugin_posts_user
option.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_posts_user: ********
The coding habits add deduced coding habits based on your recent activity, from up to 1000 events.
๐ฌ About
It will consume an additional GitHub request per event fetched.
Because of GitHub REST API limitation, provided token requires full repo
scope to access private events.
Events that cannot be fetched will be ignored so it is still possible to use this plugin with a scope-less token.
A high value must be provided for plugin_habits_from
in order for this section to be accurate, although it'll increase the number of GitHub requests sent.
If you're using GitHub Api in other projects, you could reach the rate limit.
These facts are generated from your recent coding activity. The indent style is deduced from the diffs of your recent commits.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_habits: yes
plugin_habits_from: 200
plugin_habits_days: 14
You can display charts in this section :
These charts are generated from your recent coding activity. Languages metrics are computed with github/linguist from the diffs of your recent commits.
Add the following to your workflow instead :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_habits: yes
plugin_habits_from: 200
plugin_habits_days: 14
plugin_habits_facts: yes
plugin_habits_charts: yes
By default, dates are based on the Greenwich meridian (England time). In order to these metrics to be accurate, be sure to set your timezone (see here for a list of supported timezones) :
- uses: lowlighter/metrics@latest
with:
# ... other options
config_timezone: Europe/Paris
The gists plugin displays your gists metrics.
๐ฌ About
It will consume an additional GitHub request per gist fetched.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_gists: yes
The stars plugin displays your recently starred repositories.
๐ฌ About
It will consume an additional GitHub request.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_stars: yes
plugin_stars_limit: 4
The stargazers plugin displays your stargazers evolution across all of your repositories over the last two weeks.
๐ฌ About
It will consume additional GitHub requests per repository per set of 100 stargazers.
Add the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
plugin_stargazers: yes
A few additional options are available. See all supported options in action.yml.
๐ฌ About
By default, dates are based on the Greenwich meridian (England time).
It is possible to set set your timezone (see here for a list of supported timezones) by adding the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
config_timezone: Europe/Paris
Generated metrics height is computed after being rendered through an headless browser. As rendering can depends on used fonts and operating system, it may render as cropped or with additional blank space at the bottom.
It is possible to adjust the padding by adding the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
config_padding: 6%
Both positive and negative values are accepted, but you must specify a percentage.
It is possible to convert output from SVG to PNG or JPEG images by adding the following to your workflow :
- uses: lowlighter/metrics@latest
with:
# ... other options
config_output: png
Note that png
does not support animations while jpeg
does not support both animations and transparency.
To suggest a new feature, find a bug or need help, fill an issue describing your problem or your needs.
If you're motivated enough, you can submit a pull request to integrate new features or to solve open issues.
Read CONTRIBUTING.md for more information about this.
- GitHub GraphQL API
- GitHub GraphQL Explorer
- GitHub Rest API
- GitHub Octicons
- See GitHub Logos and Usage for more information.