Skip to content

Profile README ​

ghusage can write its reports as Markdown, so a scheduled GitHub Actions workflow can keep a section of your profile README up to date.

sh
ghusage overview --since 30d --public-only --format markdown
markdown
### GitHub activity of octocat

Overview · 2026-10-24 → 2026-11-22 (Asia/Tokyo)

| Metric | Value |
| --- | --- |
| Commits | 142 (3 merge) |
| PRs created | 12 |
...

#### Top repositories

| Repository | Vis | Commits | PRs | ... |
| --- | --- | ---: | ---: | ... |
| octocat/hello-world | public\* | 98 | 7 | ... |

<sub>Coverage: complete · last sync 2026-11-22 09:00 · generated by ghusage</sub>

--format markdown works with overview, daily, weekly, monthly, yearly and repos. Other commands reject it with exit code 2.

1. Mark the place in your README ​

Your profile README lives in the repository named after your account (<you>/<you>). Add two marker lines where the report should go. Everything between them is replaced on each run.

markdown
<!-- ghusage:start -->
<!-- ghusage:end -->

2. Create a token ​

The default GITHUB_TOKEN of a workflow cannot be used: it only sees the repository the workflow runs in, and it does not act as you.

For a public README, create a classic personal access token with no scopes (Settings → Developer settings → Personal access tokens → Tokens (classic)). Without scopes it can read public data only, which is all a public README should show. Fine-grained tokens are not suitable here: they only see the repositories they were granted, so activity in other people's repositories would be missing.

Add the token to the profile repository as an Actions secret named GHUSAGE_TOKEN (Settings → Secrets and variables → Actions).

3. Add the workflow ​

Create .github/workflows/ghusage.yml in the profile repository:

yaml
name: Update GitHub activity

on:
  schedule:
    - cron: "0 0 * * *" # every day at 00:00 UTC
  workflow_dispatch:

permissions:
  contents: write

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Keep the cache between runs so each run only syncs what changed.
      - uses: actions/cache@v4
        with:
          path: ${{ runner.temp }}/ghusage
          key: ghusage-${{ github.run_id }}
          restore-keys: ghusage-

      - name: Build the report
        env:
          GH_TOKEN: ${{ secrets.GHUSAGE_TOKEN }}
          GHUSAGE_DATA_DIR: ${{ runner.temp }}/ghusage
        run: |
          npx -y ghusage@latest overview --since 30d --public-only \
            --timezone Asia/Tokyo --require-complete \
            --format markdown > "$RUNNER_TEMP/ghusage.md"

      - name: Put it into the README
        run: |
          python3 - "$RUNNER_TEMP/ghusage.md" README.md <<'EOF'
          import re, sys
          report = open(sys.argv[1], encoding="utf-8").read()
          readme = open(sys.argv[2], encoding="utf-8").read()
          start, end = "<!-- ghusage:start -->", "<!-- ghusage:end -->"
          pattern = re.compile(re.escape(start) + ".*?" + re.escape(end), re.S)
          if not pattern.search(readme):
              sys.exit("markers not found in README.md")
          readme = pattern.sub(lambda _: f"{start}\n{report}\n{end}", readme)
          open(sys.argv[2], "w", encoding="utf-8").write(readme)
          EOF

      - name: Commit if changed
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add README.md
          git diff --cached --quiet || git commit -m "Update GitHub activity"
          git push

Run it once from the Actions tab (Run workflow) to check it. Then it runs every day.

Notes ​

  • Private data. A profile README is public. Keep --public-only so private repositories are neither fetched nor shown. Without it, Markdown, like JSON and CSV, hides private repository names and titles, but numbers from private repositories would still be included in the totals.
  • Incomplete data. With --require-complete, a run whose data is not complete (for example after a rate limit or a GitHub outage) fails and leaves the README as it was, instead of writing lower numbers. The next run tries again.
  • First run. The first run has no cache and syncs the whole period, which takes longer; later runs only fetch what changed. See Syncing and the cache.
  • Other reports. Replace overview --since 30d with, for example, weekly --since 12w, monthly --since 12m or repos --since 90d.
  • Time zone. Runners use UTC. Set --timezone to your own zone so days and weeks start when yours do.