How to Add GitHub Metrics to Your Profile README

The lowlighter/metrics project is an open-source SVG generator that produces rich developer cards by combining multiple data sources. Unlike simpler stats cards, Metrics supports over 30 plugins including: contribution calendar with color-coded activity, language breakdown with time estimates, starred repository topics word cloud, coding habits (commit times by hour and day), recently starred repositories, followers and following activity, achievements unlocked, WAKATIME integration, and more.

Each plugin can be enabled or disabled independently, letting you build a card that shows exactly the information you want. The result is a single SVG file committed to your repository daily, embedded in your README as a standard image.

The recommended setup uses GitHub Actions:

1. Create a GitHub personal access token at github.com/settings/tokens with scopes: read:user, repo, read:org.
2. Add it as a repository secret named METRICS_TOKEN.
3. Create .github/workflows/metrics.yml:

name: Metrics
on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:
permissions:
  contents: write
jobs:
  github-metrics:
    runs-on: ubuntu-latest
    steps:
      - uses: lowlighter/metrics@latest
        with:
          token: ${{ secrets.METRICS_TOKEN }}
          output_action: commit
          filename: metrics.svg
          plugin_languages: yes
          plugin_languages_analysis_timeout: 15
          plugin_habits: yes
          plugin_habits_from: 200
          plugin_habits_days: 14

4. After the first run, add to your README:

![Metrics](metrics.svg)

Each plugin has a plugin_[name]: yes entry plus optional configuration sub-options. Commonly used plugins:

• plugin_languages: yes — language breakdown with byte counts and time estimates
• plugin_habits: yes — coding habits chart (times of day, days of week)
• plugin_achievements: yes — GitHub achievement badges
• plugin_calendar: yes — full-year contribution calendar
• plugin_topics: yes — starred topics word cloud
• plugin_notable: yes — notable contributions to other repositories
• plugin_wakatime: yes — WakaTime integration (requires plugin_wakatime_token secret)

The official documentation at github.com/lowlighter/metrics/blob/master/README.md lists all plugins with their full parameter reference. A live preview tool is available at metrics.lecoq.io where you can interactively configure your metrics image before committing the workflow.

If the workflow fails with a 401 or 403 error, verify that your METRICS_TOKEN has the correct scopes: read:user is required for basic profile data. Add repo scope if you want metrics from private repositories.

If the workflow runs but the SVG is not committed, ensure the workflow has permissions: contents: write and that your token has push access to the repository. If using the GITHUB_TOKEN (Actions default token) instead of a personal access token, it may not have sufficient permissions — the personal access token approach is more reliable.

For very large accounts with many repositories, the plugin_languages_analysis_timeout may need to be increased. The default language analysis can time out on accounts with thousands of repositories.