マージ前のGitHub Actionsをテスト実行するClaude Code Skillsの紹介
はじめに
GitHub Actionsのワークフローを新規に追加する際の困りごとについて紹介します。
普段の開発では全てのコード変更はPull Requestを通じて行うのですが、ワークフローの新規追加の場合は
- Pull Request作成時点で動作確認が完了している状態にしたい
- workflow_dispatchを使って動作確認する方法があるが、デフォルトブランチにマージされていないとUI上から実行できない仕様がある
というジレンマに遭遇します。ワークアラウンドとして一度空のワークフローをマージし、その後にPull Requestで修正を加えて動作確認を行う方法をよく使っていましたが、冗長なレビューが発生するなどの問題がありました。
そんな時に下記のブログ記事に出会い、一時的にpull_requestトリガーを追加する手法を知りました。今回は、この手順を自動化するためにClaude Code Agent Skillsを作成したので、その方法について紹介したいと思います。
アプローチ
ブログ記事で紹介されていた方法は以下の通りです
- 一時的に
pull_requestトリガーをワークフローファイルに追加 - Pull Requestを作成してワークフローを実行させる（これによりGitHubがワークフローを認識でき、ghコマンドからの実行が可能になる）
- 一時的なトリガーを削除
実際に試してみて使えることが分かったのですが、毎回Claude Codeに
URLを渡して実行してもらうのはすこし面倒です。そこで、この手順を自動化するためにClaude Code Agent Skillsを作成することにしました。
Claude Code Agent Skillsとは
Claude Code Agent Skillsは、Claude Codeに特定のタスクの実行方法を教えるMarkdownファイルです。PRレビューのテンプレート化やコミットメッセージの生成ルール、繰り返し行う複雑な手順の自動化などに使えます。
Claudeが会話の文脈から自動的に適切なSkillを選択して実行するほか、/test-workflow-on-branchのように明示的に呼び出すこともできます。
詳しくは公式ドキュメントを参照してください。
作成した test-workflow-on-branch スキル
以下が実際に作成したskill.mdの全文です。このファイルをユーザールートかプロジェクトルートの.claude/skills/test-workflow-on-branch/skill.mdに配置することで使えるようになります。
---
name: test-workflow-on-branch
description: GitHub Actionsのワークフローを現在のブランチで実行するスキル。デフォルトブランチにまだマージされていないワークフローファイルを動作確認する際に使用。workflow_dispatchトリガーを持つワークフローの実行をサポート。
---
# Test Workflow on Branch
まだデフォルトブランチにマージされていないGitHub Actionsのワークフローを、現在のブランチで実行するためのスキル。
## 背景
GitHub Actionsは通常、デフォルトブランチ（main/master）に存在するワークフローファイルのみがUIから手動実行できます。新しいワークフローを作成してテストしたい場合、この制限が問題になります。
このスキルは [Thomas Levesque氏のブログ記事](https://thomaslevesque.com/2024/04/25/running-a-github-actions-workflow-that-doesnt-exist-yet-on-the-default-branch/) で紹介されている手法を実装しています。
## 前提条件
- `gh` (GitHub CLI) がインストール済み
- `gh auth login` で認証済み
- ワークフローファイルに `workflow_dispatch` トリガーが設定されている
## 実行フロー（新しいワークフローファイルの場合）
### ステップ1: ワークフローファイルを作成
1. **`workflow_dispatch` トリガーのみでワークフローファイルを作成**
```yaml
name: My Workflow
on:
workflow_dispatch:
inputs:
example_input:
description: 'Example input'
required: false
default: 'default value'
jobs:
# ジョブ定義
```
2. **変更をコミット**
```bash
git add .github/workflows/<workflow-file-name.yml>
git commit -m "Add new workflow"
```
### ステップ2: 一時的に `pull_request` トリガーを追加
3. **`pull_request` トリガーを追加（一時的）**
```yaml
name: My Workflow
on:
workflow_dispatch:
inputs:
example_input:
description: 'Example input'
required: false
default: 'default value'
pull_request: # 一時的に追加（GitHubに認識させるため）
jobs:
# ジョブ定義
```
4. **変更をコミット＆プッシュ**
```bash
git add .github/workflows/<workflow-file-name.yml>
git commit -m "Add temporary pull_request trigger for GitHub recognition"
CURRENT_BRANCH=$(git branch --show-current)
git push -u origin $CURRENT_BRANCH
```
### ステップ3: Pull Requestを作成
5. **Pull Requestを作成**
```bash
gh pr create --title "Add new workflow" --body "Testing new workflow" --draft
```
**重要**: PRを作成することで、`pull_request`トリガーによりワークフローが実行され、
GitHubがワークフローを認識してActionsタブに表示されるようになる
6. **ワークフローが実行されたことを確認**
```bash
gh run list --workflow=<workflow-file-name.yml> --limit 1
```
### ステップ4: 一時的なトリガーを削除
7. **ユーザーに削除方法を確認**
一時的に追加した`pull_request`トリガーを削除する方法を2つ提示：
**方法A: revertコミットを作成（安全・推奨）**
- 利点: 履歴が保持される、安全
- 欠点: コミット履歴に一時的な変更が残る
```bash
# 直前のコミット（pull_requestトリガー追加）をrevert
git revert HEAD
git push
```
**方法B: コミットを削除してforce push（履歴をクリーンに）**
- 利点: コミット履歴がクリーン
- 欠点: force pushが必要、他の人がpullしている場合は問題になる
```bash
# 直前のコミット（pull_requestトリガー追加）を削除
git reset --soft HEAD~1
# ファイルを元の状態に戻す
git checkout HEAD -- .github/workflows/<workflow-file-name.yml>
# 変更をコミット
git add .github/workflows/<workflow-file-name.yml>
git commit -m "Remove temporary pull_request trigger"
# force push（注意: 他の人がpullしている場合は使用しない）
git push --force-with-lease
```
### ステップ5: ワークフローを手動実行
8. **現在のブランチでワークフローを手動実行**
```bash
CURRENT_BRANCH=$(git branch --show-current)
gh workflow run <workflow-file-name.yml> --ref $CURRENT_BRANCH
```
成功すると「Created workflow_dispatch event for <workflow-file-name.yml>」と表示される
9. **実行状況を確認**
```bash
gh run list --workflow=<workflow-file-name.yml> --limit 1
# または、実行の詳細を確認
gh run watch
```
### inputsを指定して実行する場合
```bash
CURRENT_BRANCH=$(git branch --show-current)
gh workflow run <workflow-file-name.yml> \
--ref $CURRENT_BRANCH \
-f input1=value1 \
-f input2=value2
```
## トラブルシューティング
### "HTTP 404: Not Found" エラー
ワークフローファイルが見つからない場合、以下を確認してください：
1. **PRが作成されているか確認**
```bash
gh pr list --head $(git branch --show-current)
```
PRが存在しない場合は、PRを作成してください：
```bash
gh pr create --title "Test workflow" --body "Testing workflow" --draft
```
2. **`pull_request` トリガーが追加されているか確認**
新しいワークフローファイルの場合、一時的に `pull_request` トリガーを追加する必要があります。
これにより、PR作成時にワークフローが実行され、GitHubがワークフローを認識します。
3. **GitHubの同期を待つ**
PRを作成してワークフローが実行された後、GitHubがワークフローを認識するまで数秒〜数十秒かかることがあります。
4. **ワークフローファイルがプッシュされているか確認**
```bash
gh browse .github/workflows/<workflow-file-name.yml> --branch $(git branch --show-current)
```
### "workflow not found" エラー
ワークフローファイルに `workflow_dispatch` トリガーが設定されているか確認してください。
### 認証エラー
```bash
gh auth login
```
を実行して認証し直してください。
### 実行が開始されない
以下のコマンドでワークフローの実行状況を確認：
```bash
gh run list --limit 5
```
## 実装上の注意点
- このスキルを使用する際は、必ずユーザーにワークフローファイル名を確認してから実行すること
- ワークフローの inputs が必要な場合は、ユーザーに確認してから `-f` オプションで指定すること
- 実行後は、実行IDやURLをユーザーに提示すること
- 一時的な `pull_request` トリガーの削除方法は、必ずユーザーに確認してから実行すること（ステップ4参照）
実際の使用イメージ
以下のように動作します。
画像のように文脈を判断して自動的に読み込んでくれますが、/test-workflow-on-branchで明示的に呼び出すことも可能です。
工夫したポイント
ブログの手順は自然言語で書かれているため、作業に必要なステップが明示されていませんでした。そこで、一度pull_requestトリガーを追加してPull Requestを作成するステップなどを細かく分けて、Claudeが迷わず実行できるように工夫しました。
また、動作確認の際にはpull_requestトリガーを追加してpushする関係で、commit履歴が汚れてしまう問題があります。これを解決するために、revert以外にreset+force pushで履歴をクリーンに保つ方法も提示するようにしています（勝手にやられると嫌な操作なので確認するようにもしています）
最後に
Claude Code Agent Skillsを作成することで、GitHub Actionsのワークフローをテストする際のハック手法を自動化することができました。同じような課題を抱えている方の参考になれば幸いです。
よかったらXのフォローもよろしくお願いします！
Discussion