GitHub Actionsのワークフロー作成をClaude Codeで進める手順
Claude CodeにGitHub Actionsのワークフローyamlを書かせる手順と、on・jobs・runs-onなど主要キーの読み方、バージョン固定や権限設定の落とし穴を紹介します。
Claude CodeでGitHub Actionsのワークフローを作成する流れ
GitHub Actionsのワークフローとは、リポジトリの.github/workflowsディレクトリに置くYAMLファイルで、pushやpull requestなどのイベントをきっかけにビルド・テスト・デプロイを自動実行する仕組みです。ワークフローはonで起動条件を、jobsで実行内容を定義します。
手書きだとキーの綴りやインデントを間違えやすく、拡張子やディレクトリの制約も細かくあります。Claude Codeにリポジトリの構成と実行したい処理を伝えれば、この定義ファイルを自然言語の指示から組み立てられます。
本記事は、Claude Codeにワークフローyamlそのものを書かせる手順を扱います。Claude Code自体をGitHub Actions上で動かして自動レビューやheadless実行をしたい場合は、Claude CodeをGitHub Actionsに組み込む記事を参照してください。目的が逆になるので、混同しないよう先に触れておきます。
作成を始める前に必要なもの
必要なのは、GitHub上のリポジトリとClaude Codeのセットアップだけです。事前準備が整っていれば、最初のワークフローは数分で用意できます。
- GitHub Actionsが有効なリポジトリ
- セットアップ済みのClaude Code(リポジトリのルートで起動できる状態)
- ワークフローで実行したい処理の見当(テスト・lint・ビルド・デプロイなど)
ワークフローファイルは.github/workflowsディレクトリに置き、拡張子は.ymlまたは.yamlである必要があります。GitHubはこのディレクトリ配下のファイルだけをワークフローとして認識するため、置き場所を誤ると実行されません。
ステップ1: 実行したい処理をClaude Codeに伝える
最初のステップは、起動条件と実行内容を自然言語で指示することです。「pushで走らせる」「pull requestのときだけ」といったタイミングと、テストやビルドといった処理内容を伝えます。
.github/workflows/ci.ymlを新規作成して。mainへのpushとpull_requestで走らせ、
Node.js 24でnpm ciとnpm testを実行するCIワークフローにしてClaude Codeはリポジトリのpackage.jsonなど既存の設定を読み取り、on・jobs・stepsを含むYAMLの草稿を生成します。
ステップ2: 生成されたYAMLの構成を確認する
生成された草稿は、保存する前に主要キーの役割を確認します。読み方を知っておくと、意図と違う箇所だけを指示し直せます。
| キー | 役割 |
|---|---|
on | 役割ワークフローを起動するイベント(push・pull_request・scheduleなど) |
jobs.<job_id> | 役割並行して走る処理の単位。既定では複数jobが並列実行される |
runs-on | 役割jobを実行するランナー環境(ubuntu-latestなど) |
steps | 役割jobの中で順に実行する処理。usesで既存アクション、runでシェルコマンドを呼ぶ |
たとえば、上のステップ1の指示に対しては、次のようなYAMLが生成されます。
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v7
with:
node-version: 24
- run: npm ci
- run: npm testjobsは既定で並列に実行されるので、テストとデプロイのように順序が必要な処理は、後述のneedsで明示的につなぎます。
ステップ3: コミットして実行結果を確認する
ファイルをコミットしてpushすると、対象イベントに一致した時点でワークフローが自動的に起動します。
git add .github/workflows/ci.yml
git commit -m "add: CIワークフローを追加"
git push実行結果は、リポジトリの「Actions」タブから確認できます。左サイドバーでワークフロー名を選び、実行履歴からログを開くと、各ステップの出力を個別に確認できます。ステップごとにログが展開できるので、失敗したrunだけを絞り込んで見られます。
手動実行やスケジュール実行にも対応させる
pushやpull_request以外に、手動実行や時刻指定の定期実行もClaude Codeに追加してもらえます。トリガーを増やすだけの指示で、既存のワークフローにonの項目が追加されます。
workflow_dispatchを使うと、Actionsタブから任意のタイミングで手動実行できるようになります。environmentのような入力項目を定義すれば、実行時に選択肢やテキストで値を渡せます。
on:
workflow_dispatch:
inputs:
environment:
description: "デプロイ先"
required: true
type: choice
options:
- staging
- production定期実行にはon.scheduleでcron形式の時刻を指定します。スケジュール実行はデフォルトブランチの最新コミットに対して走り、指定できる最短間隔は5分です。
on:
schedule:
- cron: "30 5 * * 1-5"on.scheduleの時刻は既定でUTC解釈になります。上の30 5 * * 1-5はUTC 5:30、つまり日本時間(JST、UTC+9)では14:30の起動です。日本時間で指定したい時刻をそのままcronに書くと9時間ずれるため、Claude Codeに指示するときも「日本時間14:30に実行して」のように伝え、生成されたcron値がUTC換算で合っているかを確認します。
複数jobを順番に実行し、失敗時も後処理を走らせる
デプロイのように「テストが通ったらデプロイする」という順序がある場合、jobs.<job_id>.needsで依存するjobを指定します。
jobs:
test:
runs-on: ubuntu-latest
steps:
- run: npm test
deploy:
needs: test
runs-on: ubuntu-latest
steps:
- run: echo "deploy"依存元のjobが失敗またはスキップされると、それに依存するjobも既定でスキップされます。それでも通知のような後処理だけは必ず走らせたい場合は、if: ${{ always() }}を組み合わせるようClaude Codeに指示します。
環境変数をワークフロー全体で共有する
すべてのjobで共通して使う値は、secretsではなくenvで定義すると使い回せます。ワークフロー全体・job単位・step単位のどのレベルでも設定でき、同じ名前を複数レベルで定義した場合はstepの値が最も優先されます。
env:
NODE_ENV: test
jobs:
test:
runs-on: ubuntu-latest
steps:
- run: npm test既存のワークフローの修正もClaude Codeに任せられる
新規作成だけでなく、既存の.github/workflows/*.ymlを読み込んで直す指示もそのまま通ります。「このワークフローにmatrixを追加して」「Node.jsのバージョンを20に上げて」のように、変更したい箇所だけを伝えれば十分です。
既存ファイルを編集する場合も、保存前にgit diffで変更前後を確認する運用にすると、意図しない箇所まで書き換えられていないかその場で気づけます。大きな構成変更のときは、変更点を1つずつ指示して都度差分を見るほうが、意図しない削除に気づきやすくなります。
secretsを安全に渡す
APIキーやデプロイ用のトークンは、YAMLに直接書かずリポジトリのSecretsに登録し、secretsコンテキスト経由で参照します。Claude Codeに指示するときも「値そのものではなくsecrets名を使う」ことを明確に伝えます。
secretsはwithの入力として渡すか、envで環境変数として渡します。
steps:
- name: デプロイ
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
run: |
example-deploy --token "$DEPLOY_TOKEN"if:の条件式ではsecretsを直接参照できません。条件分岐が必要な場合は、まずjob単位の環境変数に代入してから、その環境変数を条件式で参照する形にします。また、secretsが未設定のときに参照した値は空文字列になるため、必須のsecretsはワークフロー側で存在チェックを入れておくと事故を防げます。
Claude Codeに任せてよい場面と、レビューが必要な場面
Claude Codeへの丸投げが向くのは、雛形作りや典型的なCI構成です。権限やシークレットが絡む部分は、生成後に必ず人が目を通します。
| 用途 | おすすめ度 | 理由 |
|---|---|---|
| lint・テストの雛形作成 | おすすめ度◎ | 理由定型的で、既存の設定ファイルから処理内容を推測しやすい |
| 複数OS・複数バージョンのmatrix構成 | おすすめ度○ | 理由組み合わせ自体は作れるが、上限256jobsなどの制約は自分でも確認する |
| デプロイ用のsecrets・permissions設定 | おすすめ度△ | 理由生成後に権限の絞り込みを必ず見直す |
| self-hosted runnerのラベル設計 | おすすめ度△ | 理由実行環境固有の情報が必要で、環境側の確認が欠かせない |
よくあるつまずき
生成直後のYAMLはそのまま動くことが多い一方、運用上の弱点がそのまま残ることがあります。次の点は保存前に確認します。
-
アクションのバージョン指定:
uses: actions/checkout@mainのようにブランチ名を指定すると、アクション側の更新で挙動が変わる可能性があります。タグやコミットSHAで固定するほうが安定します。 -
GITHUB_TOKENの権限:permissionsを指定しない場合、既定の権限がそのまま使われます。一方でpermissionsを1つでも書くと、そこに列挙しなかった権限はすべてnoneになります。書き込みが不要なjobには、必要な権限だけを明示するのが安全です。permissions: contents: read -
runの文字数上限: 1つのrunステップで実行できるコマンドは21,000文字までです。長いスクリプトはrunに直書きせず、リポジトリ内のシェルスクリプトを呼び出す形にします。 -
matrixの組み合わせ数:
strategy.matrixには最大256jobsという上限があります。OSとバージョンを両方展開すると、想定より多くのjobが一気に生成されます。 -
YAMLのインデント崩れ: タブ文字は使えず、半角スペースでインデントを揃える必要があります。生成結果でもインデントのズレは目視で確認します。
-
secretsのコマンドライン直書き:
runの中でsecretsをコマンドライン引数に直接展開すると、psコマンドなどから見えてしまう可能性があります。env経由で渡し、シェル側で引用符で囲むのが安全です。 -
workflow_dispatchが反応しない:workflow_dispatchはワークフローファイルがデフォルトブランチにある場合しか手動実行を受け付けません。ブランチを作って追加した直後は、一度mainにマージするまでActionsタブに表示されないことがあります。
まとめ
Claude CodeにGitHub Actionsのワークフローを書かせると、on・jobs・stepsという基本構造を意識するだけで、動くYAMLの草稿がすぐ手に入ります。手動実行やスケジュール実行、secretsの受け渡しといった応用も、同じように自然言語で指示を追加していけます。生成後にバージョン指定と権限設定を見直す一手間を挟めば、そのまま運用に乗せられます。
複数のパラメータを渡したいワークフローはGitHub ActionsのパラメータとCLI引数をClaude Codeで渡す記事、組織全体に同じ構成を展開したい場合はClaude CodeのGitHub Actionsを組織全体に導入する手順も参考にしてください。GitHub Actions以外のワークフロー基盤をClaude Codeで書く例は、Claude CodeでPrefectのワークフローを書く記事にまとめています。