Setup a GitHub Action which runs periodically and pushes generated images to a repository.
Create a repository with the same name as your GitHub login (if it doesn't exist).
Its README.md
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 scopes are required, but additional one may be required depending on which features will be used. Each plugin documentation enumerates which scopes are required to make it work.
A a general rule, the following scopes may be required:
public_repo
for some pluginsread:org
for all organizations related metricsrepo
for all private repositories related metricsread:user
for some private repositories related metrics
gist
for publishing renders to gists instead of a repository
💡 For security reasons, it is advised to always use the least amount of scopes. It is possible to prevent security issues by forking this repository and using it in your workflow instead (more information available in step 3)
A scope-less token can still display private contributions by enabling Include private contributions on my profile
in account settings:
When a plugin has not enough scopes to operate (and plugins_errors_fatal
is disabled), an error will be reported in the rendering like below:
Go to the Settings
of your repository and to create a new secret and paste your freshly generated GitHub token there.
Create a new workflow from the Actions
tab of repository and paste the following:
name: Metrics
on:
# Schedule daily updates
schedule: [{cron: "0 0 * * *"}]
# (optional) Run workflow manually
workflow_dispatch:
# (optional) Run workflow when pushing on master/main
push: {branches: ["master", "main"]}
jobs:
github-metrics:
runs-on: ubuntu-latest
steps:
- uses: lowlighter/metrics@latest
with:
token: ${{ secrets.METRICS_TOKEN }}
Rendered metrics will be committed to repository on each run.
There are several metrics versions that can be used in workflows:
@latest
- ✔️ Stable version
@master
/@main
- ✔️ Enjoy new features and bug fixes as they're being released
- ✔️ Helps discovering new issues
- ➖ Jobs may fail occasionally (watch issues and discussions for bug tracking)
@{fork}
- ✔️ Secure as you're in control
- ✔️ Advised when using additional scopes in personal access token
- ➖ Manual updates (watch new releases for updates)
@v{x}.{x}
- ➖ Pinned versions have no real advantages
💡 Workflows are always compatible with previous version as metrics workflow-breaking changes are never introduced. In fact, even workflows from v1.0 are still compatible!
Example: using a forked version
- uses: user/metrics@master
⚠️ Be sure to use the default branch (@master
) on forks to apply any changes made!
Read documentation for more informations about configuration.
It is advised to start with 🧱 core
plugin documentation.
It is also possible to use metrics.lecoq.io to play with configuration options, preview renders and finally copy the auto-generated workflow code.
Update profile README.md
to include rendered image (filename may differ if filename
option has been set, use the correct path accordingly).
Example: add rendered image with markdown
![Metrics](/github-metrics.svg)
Example: add rendered image with html for more customization
<img align="center" src="/github-metrics.svg" alt="Metrics" width="400">
Example: add rendered image when using config_display: columns
<img src="/github-metrics.svg" alt="Metrics" width="100%">