📊 Metrics

Generate your metrics that you can embed everywhere, including your GitHub profile readme! It works for both user and organization accounts, and even for repositories!

For user accounts	For organization accounts

🧩 20 plugins
📰 Recent activity	🌸 Anilist
	Manga version Favorites characters version
🎟️ Follow-up of issues and pull requests	🎫 Gists
💡 Coding habits	📅 Isometric commit calendar
Charts version	Full year version
🈷️ Most used languages	👨‍💻 Lines of code changed
With both total bytes size and percentage version
🎼 Music plugin	💉 Nightscout
🎼 Favorite tracks version Recently listened version
⏱️ Website performances	🧑‍🤝‍🧑 People plugin
Detailed version With screenshot version	Followed people version Special thanks version Repository template version
✒️ Recent posts	🗂️ Projects
✨ Stargazers over last weeks	🌟 Recently starred repositories
📌 Starred topics	🧮 Repositories traffic
Mastered and known technologies version
🐤 Latest tweets	⏰ WakaTime plugin
More to come soon!

🖼️ 3 templates
📗 Classic	📘 Repository
📙 Terminal	📕 Community templates
	See documentation 🌍

🦑 Interested to get your own?

Try it now at metrics.lecoq.io with your GitHub username!

Some plugins are not are not available at metrics.lecoq.io, for a fully-featured experience use it 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 to your repository. See all supported options in action.yml.

Assuming your username is my-github-user, you can then embed rendered metrics in your readme like below:

<!-- If you're using "master" as default branch -->
![Metrics](https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg)
<!-- If you're using "main" as default branch -->
![Metrics](https://github.com/my-github-user/my-github-user/blob/main/github-metrics.svg)

💬 How to setup?

0. Setup your personal repository

Create a repository with the same name as your GitHub login (if it's not already done).

Its README.md will be displayed on your user profile:

1. Create a GitHub personal token

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

No additional scopes are needed for basic metrics, but you may have to grant additional scope depending on what features you're planning to use:

• public_repo scope for some plugins
• read:org scope for all organizations related metrics
• repo scope for all private repositories related metrics

A scope-less token can still display private contributions by enabling Include private contributions on my profile in your account settings:

If a plugin has not enough scopes to operate (and plugins_errors_fatal isn't enabled), it'll be reported in the rendering like below:

2. Put your GitHub perosnal token in your repository secrets

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

3. Create a GitHub Action workflow in your repository

Create a new workflow from the Actions tab of your repository and paste the following:

name: Metrics
on:
  # Schedule updates (each hour)
  schedule: [{cron: "0 * * * *"}]
  # Lines below let you run workflow manually and on each commit (optional)
  push: {branches: ["master", "main"]}
  workflow_dispatch:
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.

Rendered metrics will be committed to your repository on each run.

Choosing between @latest, @master or a fork

If you wish to use new features as they're being released, you can switch from @latest to @master. As the latter is used as a development branch, jobs may fail from time to time (although we try to mitigate this).

When using a token with additional permissions, it is advised to fork this repository and use it instead to minimize security risks:

      - uses: my-github-username/metrics@master
      # If you make changes on your fork, be sure not leave @latest as tag!

In this case, please consider watching new releases to stay up-to-date and enjoy latest features!

@latest will be updated on each release soon after Planned for next release is emptied. Metrics doesn't introduce breaking changes from an user point of view (i.e. your workflows will always be valid) so you can follow release cycles without worrying.

Examples workflows

Metrics displayed on this page are rendered from this workflow so you can check it out for some code examples about plugins usage.

You can also take a look at this user workflow if you want.

4. Embed link into your README.md

Update your README.md to embed your metrics:

<!-- If you're using "master" as default branch -->
![Metrics](https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg)
<!-- If you're using "main" as default branch -->
![Metrics](https://github.com/my-github-user/my-github-user/blob/main/github-metrics.svg)

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

For convenience, you can use the shared instance available at metrics.lecoq.io without any additional setup.

![Metrics](https://metrics.lecoq.io/my-github-user)

This is mostly intended for previews, to enjoy all features consider using GitHub Action instead.

💬 Fair use

To ensure service availability, shared instance has a few limitations:

• Images are cached for 1 hour
  • Rendered metrics won't be updated during this time window when queried
  • You can manually update rendering againg your metrics on metrics.lecoq.io
• There is a rate limiter enabled (it doesn't affect already cached metrics)
• Several plugins may not be available

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

Setup a metrics instance on your server if you don't want to use GitHub Actions and metrics.lecoq.io. See all supported options in settings.example.json.

Assuming your username is my-github-user, you can then embed rendered metrics in your readme like below:

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

💬 How to setup?

0. Prepare your server

You'll need a server with a recent version NodeJS (see used version in Dockerfile).

1. Create a GitHub personal 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

Clone repository, install dependencies and copy configuration example to settings.json:

git clone https://github.com/lowlighter/metrics.git
cd metrics/
npm install --only=prod
cp settings.example.json settings.json

3. Configure your instance and start it

Edit settings.json to configure your instance.

{
  //GitHub API token
    "token":"GITHUB_TOKEN",
  //Other options...
}

See all supported options in settings.example.json.

If you plan to make your web instance public, it is advised to restrict its access thanks to rate limiter and access list.

Once you've finished configuring metrics, start your instance:

npm start

Access your server with provided port in setting.json from your browser to ensure everything is working.

4. Embed 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 your instance as a service

To ensure that your instance will restart if it reboots or crashes, you should set it up as a service. This is described below for Linux-like systems which support 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

Following error codes may be encountered on 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

Most of options from action.yml are actually supported by web instance, though syntax is slightly different. All underscores (_) must be replaced by dots (.) and plugin_ prefixes must be dropped.

For example, to configure pagespeed plugin you'd use the following:

https://my-personal-domain.com/my-github-user?pagespeed=1&pagespeed.detailed=1&pagespeed.url=https%3A%2F%2Fexample.com

Note that url parameters must be encoded.

As for base content, which is enabled by default, sections are available through "base.<section>".

For example, to display only repositories section, use:

https://my-personal-domain.com/my-github-user?base=0&base.repositories=1

📚 Documentation

🧰 Template/plugin compatibily matrix

Template\Plugin	🗃️	📰	🌸	🎟️	🎫	💡	📅	🈷️	👨‍💻	🎼	💉	⏱️	🧑‍🤝‍🧑	✒️	🗂️	✨	🌟	📌	🧮	🐤	⏰
📗 Classic	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️
📘 Repository	✔️	❌	❌	✔️	❌	❌	❌	✔️	✔️	❌	❌	✔️	✔️	❌	✔️	✔️	❌	❌	✔️	❌	❌
📙 Terminal	✔️	❌	❌	❌	✔️	❌	❌	✔️	✔️	❌	❌	✔️	❌	❌	❌	❌	❌	❌	✔️	❌	❌

🖼️ Templates

Templates lets you change general appearance of rendered metrics. See their respective documentation for more informations about how to setup them:

• 📗 Classic
• 📘 Repository
• 📙 Terminal
• 📕 Community templates

🧩 Plugins

Plugins are features which provide additional content and lets you customize your rendered metrics. See their respective documentation for more informations about how to setup them:

• 🗃️ Base content
• 🧱 Core
• 📰 Recent activity
• 🌸 Anilist
• 🎟️ Follow-up of issues and pull requests
• 🎫 Gists
• 💡 Coding habits
• 📅 Isometric commit calendar
• 🈷️ Most used languages
• 👨‍💻 Lines of code changed
• 🎼 Music plugin
• 💉 Nightscout
• ⏱️ Website performances
• 🧑‍🤝‍🧑 People plugin
• ✒️ Recent posts
• 🗂️ Projects
• ✨ Stargazers over last weeks
• 🌟 Recently starred repositories
• 📌 Starred topics
• 🧮 Repositories traffic
• 🐤 Latest tweets
• ⏰ WakaTime plugin

🏦 Organizations metrics

While metrics targets mainly user accounts, it's possible to render metrics for organization accounts.

💬 Metrics for organizations

Setup is the same as for user accounts, though you'll need to add read:org scope, whether you're member of target organization or not.

You'll also need to set user option with your organization name.

If you're encounting errors and your organization is using single sign-on, try to authorize your personal token.

Most of plugins supported by user accounts will work with organization accounts, but note that rendering metrics for organizations consume way more APIs requests.

To support private repositories, add full repo scope to your personal token.

ℹ️ Example workflow

- uses: lowlighter/metrics@latest
  with:
    # ... other options
    token: ${{ secrets.METRICS_TOKEN }}          # A personal token from an user account with read:org scope
    committer_token: ${{ secrets.GITHUB_TOKEN }} # GitHub auto-generated token
    user: organization-name                      # Organization name

💬 Organizations memberships for user accounts

Only public memberships can be displayed by metrics by default. You can manage your membership visibility in the People tab of your organization:

For organization memberships, add read:org scope to your personal token.

💪 Customizing and contributing

Metrics is built to be easily customizable. Fork this repository, switch used action from lowlighter/metrics@latest to your fork and start coding!

To suggest a new feature, report a bug or ask for help, fill an issue describing it.

If you want to contribute, submit a pull request. Be sure to 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
• jamesgeorge007/github-activity-readme

📜 License

MIT License
Copyright (c) 2020 lowlighter