gitchart

Combine one GitHub account and one Forgejo account into paired light and dark SVG contribution charts.

Install

GitChart requires Node.js 22 or newer. Install the npm CLI globally:

npm install --global @onlymattjohnson/gitchart

Obtain tokens

GitChart reads credentials only from GITCHART_GITHUB_TOKEN and GITCHART_FORGEJO_TOKEN. Create both tokens for the same accounts passed to --github-user and --forgejo-user. Treat the tokens like passwords: give them an expiration where available, store them as secrets, and never commit them.

GitHub

Create a personal access token (classic):

1. On GitHub, open Settings → Developer settings → Personal access tokens → Tokens (classic) and choose Generate new token (classic).
2. Set a descriptive name and expiration.
3. Select the read:user scope so the contribution calendar can include totals from private and internal repositories, then generate and copy the token.
4. If an organization uses SAML SSO, authorize the token for that organization.

GitHub documents read:user as the optional scope that includes private and internal activity in a ContributionsCollection. GitChart uses the token only for a read-only GraphQL contribution-calendar query. Use a dedicated, expiring token.

Forgejo

Create a Forgejo API token:

1. On your Forgejo instance, open Settings → Applications → Generate New Token.
2. Select read:user, which covers the /user/* and /users/* GET routes GitChart calls.
3. Select All (public, private, and limited) repository and organization access so the heatmap can include private activity, then generate and copy the token.

Forgejo documents these choices in its access-token scope reference. Forgejo shows the token value only once.

Basic usage

Export the two required credentials, then run gitchart with both account names and the HTTPS URL of the Forgejo instance:

export GITCHART_GITHUB_TOKEN="your-github-token"
export GITCHART_FORGEJO_TOKEN="your-forgejo-token"

gitchart \
  --github-user octocat \
  --forgejo-user alice \
  --forgejo-url https://forgejo.example.org

On success, GitChart writes gitchart.svg and gitchart-dark.svg in the current directory. It lists both paths on stderr; stdout remains empty.

Optional rendering and output settings include:

• --timezone <iana-zone> groups Forgejo activity in that time zone instead of UTC.
• --output <path.svg> changes the light SVG path; the dark path inserts -dark before .svg. For example, --output assets/activity.svg writes assets/activity.svg and assets/activity-dark.svg.
• --show-source-counts selects the 930 by 184 source-ledger chart, which shows the combined total alongside separate GitHub and Forgejo totals. Without the flag, GitChart writes the familiar 780 by 178 card.
• --print-markup --alt <text> prints README-ready light/dark <picture> markup to stdout. Add --link <target> to wrap the picture in a link. Markup requires a relative output path; GitChart reports generated paths and diagnostics on stderr.

Run gitchart --help for command help or gitchart --version for the installed version.

GitHub Action

Use an immutable release tag and pass credentials through the same two environment variables as the CLI:

- uses: onlymattjohnson/[email protected]
  id: gitchart
  env:
    GITCHART_GITHUB_TOKEN: ${{ secrets.GITCHART_GITHUB_TOKEN }}
    GITCHART_FORGEJO_TOKEN: ${{ secrets.GITCHART_FORGEJO_TOKEN }}
  with:
    github-user: octocat
    forgejo-user: alice
    forgejo-url: https://forgejo.example.org
    output: assets/gitchart.svg

The successful step publishes light-path and dark-path. Set print-markup: true with alt to also publish markup.

Forgejo Action

Forgejo Runner 9.1.0 or newer can consume the same Action when its job image provides Node 22 or newer. Use the fully qualified GitHub reference:

- uses: https://github.com/onlymattjohnson/gitchart@v0
  env:
    GITCHART_GITHUB_TOKEN: ${{ secrets.GITCHART_GITHUB_TOKEN }}
    GITCHART_FORGEJO_TOKEN: ${{ secrets.GITCHART_FORGEJO_TOKEN }}
  with:
    github-user: octocat
    forgejo-user: alice
    forgejo-url: https://forgejo.example.org