プロフィール README
ghusage はレポートを Markdown で出力できます。GitHub Actions のワークフローを定期的に動かせば、プロフィール README の一部をいつも最新にしておけます。
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 を使えるのは、overview、daily、weekly、monthly、yearly、repos です。ほかのコマンドでは終了コード 2 のエラーになります。
1. README に目印を置く
プロフィール README は、アカウント名と同じ名前のリポジトリ(<自分>/<自分>)にあります。レポートを入れたい場所に、次の 2 行を書きます。実行のたびに、この 2 行の間が置き換わります。
<!-- ghusage:start -->
<!-- ghusage:end -->2. トークンを作る
ワークフローに標準で渡される GITHUB_TOKEN は使えません。そのワークフローが動くリポジトリしか見えず、あなた自身としても動かないからです。
公開の README なら、スコープを何も付けないクラシックの個人アクセストークンを作ってください(Settings → Developer settings → Personal access tokens → Tokens (classic))。スコープがなければ公開データしか読めず、公開の README に出すのはそれで十分です。Fine-grained トークンはここには向きません。許可したリポジトリしか見えないので、ほかの人のリポジトリでの活動が抜けてしまいます。
作ったトークンを、プロフィールのリポジトリに GHUSAGE_TOKEN という名前の Actions のシークレットとして登録します(Settings → Secrets and variables → Actions)。
3. ワークフローを置く
プロフィールのリポジトリに .github/workflows/ghusage.yml を作ります。
name: Update GitHub activity
on:
schedule:
- cron: "0 0 * * *" # 毎日 00:00 UTC(日本時間 9:00)
workflow_dispatch:
permissions:
contents: write
jobs:
update:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# 実行のあいだでキャッシュを残し、毎回の同期を差分だけにする
- 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まず Actions タブから一度手動で実行(Run workflow)して、動くことを確かめてください。あとは毎日動きます。
注意
- 非公開のデータ。 プロフィール README は公開されます。
--public-onlyは外さないでください。プライベートリポジトリを取得も表示もしなくなります。外した場合も、Markdown は JSON や CSV と同じようにプライベートリポジトリの名前やタイトルを隠しますが、プライベートリポジトリでの件数は合計に含まれます。 - 不完全なデータ。
--require-completeを付けておくと、レート制限や GitHub の障害でデータがそろわなかった回は失敗し、README は前の内容のまま残ります。少ない数字で上書きすることはありません。次の回にまた試します。 - 初回の実行。 初回はキャッシュがないので期間全体を同期し、時間がかかります。2 回目からは変わった分だけを取得します。同期とキャッシュを参照してください。
- ほかのレポート。
overview --since 30dの代わりに、たとえばweekly --since 12w、monthly --since 12m、repos --since 90dを使えます。 - タイムゾーン。 ランナーは UTC で動きます。
--timezoneに自分のタイムゾーンを指定すると、日や週の区切りが自分の時間に合います。