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.
ghusage overview --since 30d --public-only --format 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.
<!-- 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:
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 pushRun 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-onlyso 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 30dwith, for example,weekly --since 12w,monthly --since 12morrepos --since 90d. - Time zone. Runners use UTC. Set
--timezoneto your own zone so days and weeks start when yours do.