📊 Metrics

Generate your metrics that you can embed everywhere, including your GitHub profile readme !

But there's more with plugins and templates !

⏱️ Google PageSpeed plugin	📅 Isometric calendar plugin
Detailed audit version With screenshot version	Full year version
🎼 Favorite music tracks plugin	🎧 Recently listened music plugin
🈷️ Most used languages plugin	🎟️ Follow-up plugin
📌 Starred topics plugin	🗂️ Active projects plugin
Mastered and known technologies version
👨‍💻 Lines of code plugin	🧮 Repositories traffic plugin
🐤 Tweets plugin	✒️ Recent posts plugin
💡 Coding Habits plugin	🎫 Gists plugin
With charts version
✨ Stargazers evolution	🌟 Recently starred repositories
🗃️ Header special features
More to come soon !

Classic template	Terminal template
Repository template A special template to embed on any repository readme !
More to come soon !

🦑 Interested to get your own ?

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 !

📜 How to use ?

⚙️ Using GitHub Action on your profile repository (~5 min setup)

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 ?

0. Prepare your personal repository

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 :

1. Create a GitHub token

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 :

2. Set your GitHub token in your personal repository secrets

Go to the Settings of your personal repository to create a new secret and paste your freshly generated GitHub token there.

3. Create a new GitHub Action workflow on your personal repository

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 !

Preview vs release

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.

What will happen ?

A new metrics image will be generated and committed to your repository on each run.

Workflow examples

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.

4. Embed the link into your README.md

Edit your repository readme and add your metrics image :

![Metrics](https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg)

💕 Using the shared instance (~1 min setup, but with limitations)

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.

🏗️ Deploying your own web instance (~15 min setup, depending on your sysadmin knowledge)

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 ?

0. Prepare your server

You will need a server where you can setup and run a NodeJS application.

1. Create a GitHub token

From the Developer settings of your account settings, select Personal access tokens to create a new token.

No additional scopes are needed.

2. Install dependencies

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

3. Configure your instance

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.

4. Start your instance

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.

5. Embed the link into your README.md

Edit your repository readme and add your metrics image from your server domain :

![Metrics](https://my-personal-domain.com/my-github-user)

6. (optional) Setup as service on your instance

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.

Configuring base content

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.

Configuring plugins

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 _.

📚 Documentation

🖼️ Templates

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 compatibily matrix

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

Plugins are features which can provide additional metrics and features. In return, they may require additional configuration and consume additional API requests.

🗃️ Base content

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 data
• activity, 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"

🏦 Organizations memberships

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.

⏱️ PageSpeed

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://********

📅 Isometric calendar

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

🎼 Music

The music plugin can work in the following modes :

Playlist mode

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

Recently played mode

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%3A%2F%2Flocalhost

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

🈷️ Languages

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

🎟️ Follow-up

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

📌 Topics

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
• randomly

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

🗂️ Projects

⚠️ 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).

💬 Create a personal project on GitHub

On your profile, select the Projects tab :

Fill the informations and set visibility to public :

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, ...

👨‍💻 Lines

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

🧮 Traffic

⚠️ 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

🐤 Tweets

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.

✒️ Posts

The recent posts plugin displays recent articles you wrote on an external source, like dev.to.

💬 About

Supported sources are :

• dev.to

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: ********

💡 Habits

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

🎫 Gists

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

🌟 Stars

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

✨ Stargazers

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

🔧 Other options

A few additional options are available. See all supported options in action.yml.

💬 About

🌐 Set timezone

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

🔲 Adjust padding

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.

💱 Convert output to PNG/JPEG

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.

💪 Contributing and customizing

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.

📖 Useful references

• GitHub GraphQL API
• GitHub GraphQL Explorer
• GitHub Rest API
• GitHub Octicons
  • See GitHub Logos and Usage for more information.

✨ Inspirations

• anuraghazra/github-readme-stats
• jstrieb/github-stats
• ankurparihar/readme-pagespeed-insights
• jasonlong/isometric-contributions