Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 52 additions & 22 deletions scripts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,27 @@

smkwlab organization 運用補助スクリプト。

## distribute-claude-review.sh
## distribute-workflow.sh

Claude Code Review の caller ワークフローを、指定したリポジトリ群へ配布します。
caller は共有 reusable
`smkwlab/.github/.github/workflows/claude-code-review.yml@<ref>` を呼び出します。
共有 caller ワークフローを、指定したリポジトリ群へ配布する**汎用**スクリプト。

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✨ [POSITIVE] ワークフロー配布スクリプトの汎用化に伴い、READMEが非常に分かりやすく更新されています。特に、callerテンプレートの表と新しいワークフローを追加する手順は、今後の運用と拡張性を大きく助けるでしょう。

特定のワークフロー(レビュー等)やシークレット(`ANTHROPIC_API_KEY` 等)に依存せず、
`scripts/callers/<caller>.yml` のテンプレートを各対象リポジトリの
`.github/workflows/<caller>.yml` として設置し、`smkwlab/.github` 内の同名 reusable を
`@<ref>` で呼び出させます。

**新しい共有ワークフローを配布したくなったら、`scripts/callers/` にテンプレートを
1つ追加するだけ**です(スクリプト本体の変更は不要)。ワークフロー固有の事情(必要な
シークレット・PR 注記・可変値)は caller 側に置きます。

### 用意済みの caller テンプレート

| caller | 配布先ファイル | 役割 | 必要な前提 |
|--------|----------------|------|-----------|
| `claude-code-review` | `.github/workflows/claude-code-review.yml` | PR 自動レビュー | org secret `ANTHROPIC_API_KEY` |
| `claude-mention` | `.github/workflows/claude-mention.yml` | `@claude` 対話・修正依頼 | org secret `ANTHROPIC_API_KEY` |

`scripts/distribute-workflow.sh --list-callers` で一覧できます。各 caller の前提は
`scripts/callers/<caller>.pr-note.md`(PR 本文に付く注記)にも書かれています。

### 設計(安全側の既定)

Expand All @@ -17,49 +33,63 @@ caller は共有 reusable

### 前提

- `gh`(GitHub CLI)が対象リポジトリへの write 権限を持つアカウントで認証済み
- org シークレット `ANTHROPIC_API_KEY` が各対象リポジトリで利用可能であること
(Org Settings → Secrets → Actions)。**本スクリプトはシークレットを管理しません**
- `gh`(GitHub CLI)が対象リポジトリへの write 権限を持つアカウントで認証済みであること

これがスクリプト自体の唯一の前提です。**ワークフローが動くために必要なシークレット等は
caller ごとに異なり、本スクリプトは関与しません**(上表「必要な前提」を参照)。

### 使い方

```bash
# 候補(非アーカイブの smkwlab リポジトリ)を一覧
scripts/distribute-claude-review.sh --list-candidates
# caller テンプレート / 配布候補を一覧
scripts/distribute-workflow.sh --list-callers
scripts/distribute-workflow.sh --list-candidates

# 1) まず1リポジトリで dry-run(何も変更しない)
scripts/distribute-claude-review.sh sotsuron-template
scripts/distribute-workflow.sh claude-mention sotsuron-template

# 2) 問題なければ --apply で実行(重要リポジトリは opus)。まずここで検証する
scripts/distribute-claude-review.sh --apply --model opus sotsuron-template
scripts/distribute-workflow.sh --apply --model opus claude-mention sotsuron-template

# 3) PR が正常にレビューを起動することを確認してから、横展開(sonnet)
scripts/distribute-claude-review.sh --apply \
wr-template sotsuron-report-template ise-report-template latex-template
# 3) 動作を確認してから横展開
scripts/distribute-workflow.sh --apply claude-mention \
wr-template ise-report-template latex-template poster-template
```

### オプション

| オプション | 既定 | 説明 |
|-----------|------|------|
| `--apply` | (dry-run) | 実際に変更する |
| `--model <m>` | `sonnet` | `sonnet` / `opus` / `haiku`。卒論・修論など重要リポジトリは `opus` |
| `--ref <ref>` | `v1` | 呼び出す reusable の参照(タグ/ブランチ/SHA) |
| `--language <lang>` | `日本語` | `review_language` の値 |
| `--ref <ref>` | `v1` | 呼び出す reusable の参照(`__REF__` を置換)。タグ/ブランチ/SHA |
| `--var KEY=VALUE` | — | テンプレ/注記中の `__KEY__` を VALUE に置換(複数指定可)。caller 任意のつまみ。`--var` は `--ref`/`--model`/`--language` より優先(例: `--var REF=x` は `--ref` を上書き) |
| `--model <m>` | — | `--var MODEL=<m>` の別名(Claude caller 用の利便) |
| `--language <lang>` | — | `--var LANGUAGE=<lang>` の別名 |
| `--direct` | (PR) | デフォルトブランチへ直接コミット(branch protection の無いリポジトリ向け) |
| `--branch <name>` | `add-claude-code-review` | PR 用ブランチ名 |
| `--branch <name>` | `add-<caller>` | PR 用ブランチ名 |
| `--list-callers` | — | caller テンプレートを一覧して終了 |
| `--list-candidates` | — | 非アーカイブの smkwlab リポジトリを表示して終了 |
| `-h`, `--help` | — | ヘルプ |

### 新しい共有ワークフローを配布対象に追加するには

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✨ [POSITIVE] scripts/README.mdに「新しい共有ワークフローを配布対象に追加するには」というセクションが追加されたことで、将来的に新しいワークフローを追加する際のプロセスが明確になり、非常に分かりやすくなりました。これは、この汎用化されたスクリプトの利用を促進する上で重要な改善です。


1. `smkwlab/.github` に reusable 本体(`.github/workflows/<name>.yml`、`workflow_call`)を用意する
2. `scripts/callers/<name>.yml` に caller テンプレートを置く
- 設置先・呼び出し先は `<name>` で決まる(`uses: smkwlab/.github/.github/workflows/<name>.yml@__REF__`)
- 可変値は `__REF__` や任意の `__KEY__` トークンで埋め込み、配布時に `--ref` / `--var` で与える
(GitHub の `${{ ... }}` 式はそのまま残る)
3. (任意)`scripts/callers/<name>.pr-note.md` に PR 本文へ付ける注記(必要なシークレット等)を書く
4. `scripts/distribute-workflow.sh <name> <repos...>` で配布

### 配布後の確認

caller を追加したら、対象リポジトリで PR を1つ作成(または既存 PR を更新)し、
Claude のレビューコメントが日本語で付くことを確認してください。`ANTHROPIC_API_KEY`
が未設定のリポジトリでは reusable 側が安全にスキップします
caller を追加したら対象リポジトリで動作を確認してください(確認方法は caller による:
レビューなら PR 作成、`@claude` なら mention コメント等)。必要な前提が満たされて
いないリポジトリでは reusable 側が安全にスキップする設計を推奨します

### 注意

- **まず1リポジトリで検証**してから横展開すること(ブリーフの方針)
- **まず1リポジトリで検証**してから横展開すること
- 学生リポジトリはテンプレートから生成されるため、テンプレートに caller を入れると
以降の新規リポジトリへ伝播します。既存の学生リポジトリへ反映するには
`thesis-student-registry` の `propagate-workflow`(registry-manager)を併用します
Expand Down
2 changes: 2 additions & 0 deletions scripts/callers/claude-code-review.defaults
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
MODEL=sonnet
LANGUAGE=日本語
4 changes: 4 additions & 0 deletions scripts/callers/claude-code-review.pr-note.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
PR への自動レビュー(Claude)を有効化します。

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✨ [POSITIVE] 各callerの.pr-note.mdファイルは、生成されるPRの本文に重要な情報(必要なシークレットなど)を自動的に含めることができ、非常に有用です。これにより、配布されたワークフローの前提条件が明確になり、利用者の混乱を防ぎます。


- 動作には org シークレット `ANTHROPIC_API_KEY` がこのリポジトリで利用可能である必要があります(未配布なら安全にスキップ)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ [LOW] 以前の distribute-claude-review.sh のPR本文にあった「draft はスキップ(ready_for_review で起動)」「fork PR では secret が渡らないため安全にスキップ」といった運用上の重要な注意点を追記すると、配布するユーザーにとってより親切になるでしょう。これらの情報は、ワークフローの動作を理解する上で役立ちます。

- draft PR は `ready_for_review` まで、fork PR は secret 不在のため、いずれも安全にスキップします
27 changes: 27 additions & 0 deletions scripts/callers/claude-code-review.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Caller template: Claude Code Review (automatic PR review).
# Distributed by scripts/distribute-workflow.sh as
# .github/workflows/claude-code-review.yml in each target repository.
# The ref / model / language tokens below are substituted at distribution time.
name: Claude Code Review

on:
pull_request:
types: [opened, reopened, ready_for_review] # no synchronize: avoid re-reviewing every push

concurrency:
group: claude-review-${{ github.event.pull_request.number }}
cancel-in-progress: true

jobs:
review:
uses: smkwlab/.github/.github/workflows/claude-code-review.yml@__REF__

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✨ [POSITIVE] Claude Code Reviewワークフローのcallerテンプレートが適切に定義されています。__REF____MODEL____LANGUAGE__といったプレースホルダーの使用は、スクリプトの汎用性を保ちつつ、caller固有の設定を可能にする良い設計です。

permissions:
contents: read
pull-requests: write
issues: write
id-token: write
secrets:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
with:
model: __MODEL__
review_language: __LANGUAGE__
Comment on lines +26 to +27

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[warning] --model / --language を省略してスクリプトを実行すると、これらのトークンが未置換のまま(リテラルの __MODEL____LANGUAGE__)各リポジトリへ配布されます。

旧スクリプトはデフォルトを sonnet / 日本語 にしていましたが、新スクリプトではデフォルト値もバリデーションも除去されています。未置換の値が reusable ワークフローへ渡ると、不明モデル名として API コールが失敗します。

同じ問題は scripts/callers/claude-mention.yml の 32〜33 行目にも存在します。

対処案(いずれか):

  1. スクリプト側でデプロイ時に未置換トークン(__[A-Z_]+__)が残っていないか検証してエラーにする
  2. テンプレート自体に YAML デフォルト値を持たせ、トークン方式をやめる(例: reusable 側の with.model input にデフォルト値がある場合は with: ブロック自体を省略する)
  3. 旧スクリプト同様にスクリプト側でデフォルトを復活させる

2 changes: 2 additions & 0 deletions scripts/callers/claude-mention.defaults
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
MODEL=sonnet
LANGUAGE=日本語
4 changes: 4 additions & 0 deletions scripts/callers/claude-mention.pr-note.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
`@claude` メンションでの対話・修正依頼を有効化します。

- 動作には org シークレット `ANTHROPIC_API_KEY` がこのリポジトリで利用可能である必要があります(未配布なら安全にスキップ)
- 起動するのは権限保有者(OWNER / MEMBER / COLLABORATOR)のコメントのみです
33 changes: 33 additions & 0 deletions scripts/callers/claude-mention.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Caller template: Claude Mention (interactive @claude handler).
# Distributed by scripts/distribute-workflow.sh as
# .github/workflows/claude-mention.yml in each target repository.
# The ref / model / language tokens below are substituted at distribution time.
name: Claude Mention

on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
issues:
types: [opened]

jobs:
claude:
# Run only when @claude is mentioned AND the author has repository access
# (OWNER/MEMBER/COLLABORATOR), so external users cannot trigger a write run.
if: >

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✨ [POSITIVE] Claude Mentionワークフローのcallerテンプレートも適切に定義されています。特に、if条件で@claudeメンションとauthor_associationをチェックしている点は、セキュリティ面で非常に良い実装です。

(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') && contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude') && contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
(github.event_name == 'issues' && contains(github.event.issue.body, '@claude') && contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.issue.author_association))
uses: smkwlab/.github/.github/workflows/claude-mention.yml@__REF__
permissions:
contents: write
pull-requests: write
issues: write
id-token: write
secrets:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
with:
model: __MODEL__
language: __LANGUAGE__
203 changes: 0 additions & 203 deletions scripts/distribute-claude-review.sh

This file was deleted.

Loading
Loading