本文へ移動

プロフィール README ​

ghusage はレポートを Markdown で出力できます。GitHub Actions のワークフローを定期的に動かせば、プロフィール README の一部をいつも最新にしておけます。

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 を使えるのは、overview、daily、weekly、monthly、yearly、repos です。ほかのコマンドでは終了コード 2 のエラーになります。

1. README に目印を置く ​

プロフィール README は、アカウント名と同じ名前のリポジトリ(<自分>/<自分>)にあります。レポートを入れたい場所に、次の 2 行を書きます。実行のたびに、この 2 行の間が置き換わります。

markdown
<!-- 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 を作ります。

yaml
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 に自分のタイムゾーンを指定すると、日や週の区切りが自分の時間に合います。