Skip to content

๐Ÿ“Š An infographics generator with 30+ plugins and 300+ options to display stats about your GitHub account and render them as SVG, Markdown, PDF or JSON!

License

Notifications You must be signed in to change notification settings

hexixiang/metrics

Repository files navigation

๐Ÿ“Š Metrics

Build, test, analyze and publish Metrics (examples)

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!

โš ๏ธ This is the documentation of v3.18-beta (@master branch) which includes unreleased features, see documentation of v3.17 (@latest branch) here.

For user accounts For organization accounts

And you can customize these heavily with plugins, templates and hundreds of options!

๐Ÿงฉ 35+ plugins
๐Ÿ“… Isometric commit calendar ๐Ÿˆท๏ธ Most used languages
Full year isometric calendar
Half year isometric calendar
Indepth analysis (clone and analyze repositories)
Recently used (analyze recent activity events)
Default algorithm
Default algorithm (with details)
๐Ÿ“Œ Starred topics ๐ŸŒŸ Recently starred repositories
With icons
With labels
๐Ÿ“œ Repository licenses ๐Ÿ’ก Coding habits
Permissions, limitations and conditions
Licenses overview
Recent activity charts
Midly interesting facts
๐Ÿ… Repository contributors ๐ŸŽŸ๏ธ Follow-up of issues and pull requests
By contribution types
By number of contributions
Indepth analysis
Created on an user's repositories
Created by an user
๐ŸŽญ Comment reactions ๐Ÿง‘โ€๐Ÿคโ€๐Ÿง‘ People plugin
Related to an user
Related to a repository
โœจ Stargazers over last weeks ๐Ÿ—‚๏ธ Active projects
โ™ Code snippet of the day ๐Ÿ“ฐ Recent activity
๐Ÿ† Achievements ๐ŸŽฉ Notable contributions
Compact display
Detailed display
Indepth analysis
Contributions in organizations only
๐Ÿ’ฌ Discussions ๐Ÿ’ญ GitHub Community Support
๐Ÿ‘จโ€๐Ÿ’ป Lines of code changed ๐Ÿงฎ Repositories traffic
๐Ÿ““ Repositories ๐ŸŽซ Gists
๐Ÿ™‹ Introduction ๐Ÿ’• GitHub Sponsors
For an user or an organization
For a repository
GitHub sponsors card
GitHub sponsors full introduction
๐Ÿ’ซ Starlists ๐ŸŒ‡ GitHub Skyline 3D calendar
โฑ๏ธ Website performances ๐ŸŽผ Music plugin
PageSpeed scores
PageSpeed scores with detailed report
PageSpeed scores with a website screenshot
Random tracks from a playlist
Recently listened
๐Ÿ—จ๏ธ Stackoverflow plugin ๐ŸŒธ Anilist watch list and reading list
For anime watchers
For manga readers
Favorites characters
๐Ÿค Latest tweets โœ’๏ธ Recent posts
Latest tweets
Latest tweets with attachments
Latest posts
Latest posts width description and cover image
๐Ÿ—ผ Rss feed โฐ WakaTime plugin
๐Ÿ’น Stock prices
๐ŸŽฒ Community plugins
๐Ÿ–ผ๏ธ 4+ templates
๐Ÿ“— Classic template ๐Ÿ“˜ Repository template
๐Ÿ“™ Terminal template ๐Ÿ“’ Markdown template
๐Ÿ“• Community templates
See documentation ๐ŸŒ

๐Ÿฆ‘ Interested to get your own?

For a fully-featured experience you should use metrics as a GitHub Action, but you can also try it now at metrics.lecoq.io with your GitHub username!

Choose ๐Ÿ“Š Metrics embed if you want to customize your GitHub profile and โœจ Metrics insights to get a quick overview of your GitHub statistics:

๐Ÿ“Š Metrics embed โœจ Metrics insights
Embed metrics images on your profile readme or blog!
Use GitHub actions for even more features!
Share your metrics with friends and on social medias!
No configuration needed!

๐Ÿ™ Features

  • Create infographics from 38 plugins, 4 templates and 233 options
  • Support users, organizations and even repositories
  • Transparent by default so it'll blend well whether light or dark mode is used
  • Save your metrics as images (SVG, PNG or JPEG), markdown, PDF or JSON
    • Upload them to GitHub through commits, pull requests and gists, or handle renders yourself
  • Works either as GitHub action or as web instance

๐Ÿ“œ 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? (click to expand)

0. Setup your personal repository

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

Setup personal repository

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

GitHub Profile Example

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
    • read:user scope may also be required for some private repositories related metrics

Setup a GitHub personal token

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

Enable "Include private contributions on my profile`"

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:

Plugin error example

2. Put your GitHub personal 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.

Setup a repository secret

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)
  workflow_dispatch:
  push: {branches: ["master", "main"]}
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 }}

See all supported options in action.yml.

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

Action update example

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

For convenience, it is possible to use @main instead of @master.

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. 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)
<!-- If you're using the "columns" display mode -->
<img src="https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg" alt="Metrics" width="100%">

๐Ÿ’• 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. Availability is not guaranteed.

๐Ÿ’ฌ Fair use (click to expand)

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 again your metrics on metrics.lecoq.io
  • A rate limiter is enabled to prevent denial of service (it doesn't affect already cached metrics)
  • Some plugins may not be available

Service is provided free of charge, so please be gentle with it ๐Ÿ™‚

๐Ÿ—๏ธ 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? (click to expand)

0. Prepare your server

You'll need a server with a recent version of Docker.

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.

Setup a GitHub personal token

2. Configure your instance

Fetch settings.example.json which contains all supported option.

wget https://raw.githubusercontent.com/lowlighter/metrics/master/settings.example.json

Edit settings.json to configure your instance.

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

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

3. Start docker container

Metrics docker images are published on GitHub Container Registry.

Configure the following variables (or hardcode them in the command in the next block):

# Select an existing docker image tag
VERSION=latest
# Path to configured `settings.json`
SETTINGS=/path/to/settings.json
# Port used internally (use the same one than in `settings.json`)
SERVICE_PORT=3000
# Port to publish
PUBLISHED_PORT=80

And start the container using the following command:

docker run -d --workdir=/metrics --entrypoint="" -p=127.0.0.1:$PUBLISHED_PORT:$SERVICE_PORT --volume=$SETTINGS:/metrics/settings.json ghcr.io/lowlighter/metrics:$VERSION npm start

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)

5. (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
ExecStart=(command to run as service)

[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

Alternative option: run an instance locally (intended for testing and development)

To run an instance without docker, you'll need to have NodeJS (see used version in Dockerfile) installed.

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

Once you've finished configuring metrics, start your instance using the following command:

npm start

You should now be able to access your server with provided port in setting.json from your browser.

๐Ÿ”— HTTP parameters (click to expand)

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

๐Ÿงฐ Plugin compatibility matrix

Template/Plugin ๐Ÿ—ƒ๏ธ ๐Ÿ“… ๐Ÿˆท๏ธ ๐Ÿ“Œ ๐ŸŒŸ ๐Ÿ“œ ๐Ÿ’ก ๐Ÿ… ๐ŸŽŸ๏ธ ๐ŸŽญ ๐Ÿง‘โ€๐Ÿคโ€๐Ÿง‘ โœจ ๐Ÿ—‚๏ธ โ™ ๐Ÿ“ฐ ๐Ÿ† ๐ŸŽฉ ๐Ÿ’ฌ ๐Ÿ’ญ ๐Ÿ‘จโ€๐Ÿ’ป ๐Ÿงฎ ๐Ÿ““ ๐ŸŽซ ๐Ÿ™‹ ๐Ÿ’• ๐Ÿ’ซ ๐ŸŒ‡ โฑ๏ธ ๐ŸŽผ ๐Ÿ—จ๏ธ ๐ŸŒธ ๐Ÿค โœ’๏ธ ๐Ÿ—ผ โฐ ๐Ÿ’น
๐Ÿ“— Classic template โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โŒ โœ”๏ธ โŒ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ
๐Ÿ“˜ Repository template โœ”๏ธ โŒ โœ”๏ธ โŒ โŒ โœ”๏ธ โŒ โœ”๏ธ โœ”๏ธ โŒ โœ”๏ธ โœ”๏ธ โœ”๏ธ โŒ โœ”๏ธ โŒ โŒ โŒ โŒ โœ”๏ธ โœ”๏ธ โŒ โŒ โœ”๏ธ โœ”๏ธ โŒ โŒ โœ”๏ธ โŒ โŒ โŒ โŒ โœ”๏ธ โœ”๏ธ โŒ โœ”๏ธ
๐Ÿ“™ Terminal template โœ”๏ธ โœ”๏ธ โœ”๏ธ โŒ โŒ โŒ โŒ โŒ โŒ โŒ โŒ โŒ โŒ โŒ โŒ โŒ โŒ โŒ โŒ โœ”๏ธ โœ”๏ธ โŒ โœ”๏ธ โŒ โŒ โŒ โŒ โœ”๏ธ โŒ โŒ โŒ โŒ โŒ โŒ โŒ โŒ
๐Ÿ“’ Markdown template โœ”๏ธ โœ“ โœ“ โœ”๏ธ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ”๏ธ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ“ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ“ โœ“
Mode/Plugin ๐Ÿ—ƒ๏ธ ๐Ÿ“… ๐Ÿˆท๏ธ ๐Ÿ“Œ ๐ŸŒŸ ๐Ÿ“œ ๐Ÿ’ก ๐Ÿ… ๐ŸŽŸ๏ธ ๐ŸŽญ ๐Ÿง‘โ€๐Ÿคโ€๐Ÿง‘ โœจ ๐Ÿ—‚๏ธ โ™ ๐Ÿ“ฐ ๐Ÿ† ๐ŸŽฉ ๐Ÿ’ฌ ๐Ÿ’ญ ๐Ÿ‘จโ€๐Ÿ’ป ๐Ÿงฎ ๐Ÿ““ ๐ŸŽซ ๐Ÿ™‹ ๐Ÿ’• ๐Ÿ’ซ ๐ŸŒ‡ โฑ๏ธ ๐ŸŽผ ๐Ÿ—จ๏ธ ๐ŸŒธ ๐Ÿค โœ’๏ธ ๐Ÿ—ผ โฐ ๐Ÿ’น
๐Ÿ‘ค User โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โŒ โœ”๏ธ โŒ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ
๐Ÿ‘ฅ Organization โœ”๏ธ โŒ โœ”๏ธ โŒ โŒ โŒ โœ”๏ธ โŒ โœ”๏ธ โŒ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โŒ โŒ โŒ โœ”๏ธ โœ”๏ธ โœ”๏ธ โŒ โœ”๏ธ โœ”๏ธ โŒ โŒ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โœ”๏ธ โŒ โœ”๏ธ
๐Ÿ““ Repository โœ”๏ธ โŒ โœ”๏ธ โŒ โŒ โœ”๏ธ โŒ โœ”๏ธ โœ”๏ธ โŒ โœ”๏ธ โœ”๏ธ โœ”๏ธ โŒ โœ”๏ธ โŒ โŒ โŒ โŒ โœ”๏ธ โœ”๏ธ โŒ โŒ โœ”๏ธ โœ”๏ธ โŒ โŒ โœ”๏ธ โŒ โŒ โŒ โŒ โœ”๏ธ โœ”๏ธ โŒ โœ”๏ธ

Note: markdown template can actually render any kind of SVG metrics using embed function

๐Ÿ–ผ๏ธ Templates

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

๐Ÿงฉ 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.

The following plugins are maintained by Metric's core team:

๐ŸŽฒ Community plugins

The following plugins are provided and maintained by Metrics's user community:

๐Ÿฆ Organizations metrics

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

Metrics (organization account)

๐Ÿ’ฌ Metrics for organizations (click to expand)

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.

Add read:org scope to personal token

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
    user: organization-name                      # Organization name
๐Ÿ’ฌ Organizations memberships for user accounts (click to expand)

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

Publish organization membership

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

Add read:org scope to 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!

See ARCHITECTURE.md for more informations about how code is structured.

To report a bug fill an issue describing it. To suggest new features or requesting help to setup metrics, check out discussions.

If you want to contribute, submit a pull request. Be sure to read CONTRIBUTING.md for more information about this.

๐Ÿ“œ License

MIT License
Copyright (c) 2020-present lowlighter

License details

See full license in LICENSE.md

Sponsors

Contributors

โ™ฅ๏ธ Become a sponsor

๐Ÿ“– Useful references

โœจ Inspirations

About

๐Ÿ“Š An infographics generator with 30+ plugins and 300+ options to display stats about your GitHub account and render them as SVG, Markdown, PDF or JSON!

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 73.3%
  • TypeScript 18.6%
  • HTML 6.2%
  • CSS 1.6%
  • Other 0.3%