GitHub Actionsのワークフロー作成をClaude Codeで進める手順

Claude CodeでGitHub Actionsのワークフローを作成する流れ

GitHub Actionsのワークフローとは、リポジトリの.github/workflowsディレクトリに置くYAMLファイルで、pushやpull requestなどのイベントをきっかけにビルド・テスト・デプロイを自動実行する仕組みです。ワークフローはonで起動条件を、jobsで実行内容を定義します。依存更新PRの検証に使う例はClaude CodeでRenovateとDependabotのPRを検証する運用にあります。

手書きだとキーの綴りやインデントを間違えやすく、拡張子やディレクトリの制約も細かくあります。Claude Codeにリポジトリの構成と実行したい処理を伝えれば、この定義ファイルを自然言語の指示から組み立てられます。

作成を始める前に必要なもの

必要なのは、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の構成を確認する

生成された草稿は、保存する前に主要キーの役割を確認します。読み方を知っておくと、意図と違う箇所だけを指示し直せます。

たとえば、上のステップ1の指示に対しては、次のようなYAMLが生成されます。

name: CI
on:
  push:
    branches: [main]
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      - run: npm test

jobsは既定で並列に実行されるので、テストとデプロイのように順序が必要な処理は、後述の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"

cronの隣にIANAタイムゾーンを書くと、UTC換算を省けます。

on:
  schedule:
    - cron: "30 14 * * 1-5"
      timezone: "Asia/Tokyo"

Claude Codeには「日本時間14:30、毎時0分は避けて」のように伝え、生成されたcron値とtimezoneの組み合わせを読み返します。

複数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に指示します。

追加したブランチ上のワークフローを手動で試す

workflow_dispatchを足したブランチを作った直後は、Actionsタブに実行ボタンが出ないことがあります。ボタンの表示条件と、ボタン以外の起動経路は次のとおりです。

gh workflow run ci.yml --ref my-branch

環境変数をワークフロー全体で共有する

すべての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のバージョンを24に上げて」のように、変更したい箇所だけを伝えれば十分です。

既存ファイルを編集する場合も、保存前に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構成です。権限やシークレットが絡む部分は、生成後に必ず人が目を通します。

よくあるつまずき

生成直後のYAMLはそのまま動くことが多い一方、運用上の弱点がそのまま残ることがあります。次の点は保存前に確認します。

• アクションのバージョン指定: uses: actions/checkout@mainのようにブランチ名を指定すると、アクション側の更新で挙動が変わる可能性があります。タグやコミットSHAで固定するほうが安定します。タグの版は各アクションのREADMEのサンプルに合わせ、actions/checkoutもactions/setup-nodeも@v7と書かれています。

• 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経由で渡し、シェル側で引用符で囲むのが安全です。

• pathsやbranchesで絞ったワークフローが必須チェックになっている: フィルタで実行がスキップされると、そのワークフローのチェックは「Pending」のまま残ります。必須チェックに指定していると、そのpull requestはマージできません。

まとめ

生成されたyamlで人の目が要るのは、アクションの版、permissions、secretsの渡し方の3点です。定期実行を足すときは、時刻がUTCである点と毎時0分を避ける点を指示に含めておくと、読み返す箇所が減ります。

複数のパラメータを渡したいワークフローはGitHub ActionsのパラメータとCLI引数をClaude Codeで渡す記事、組織全体に同じ構成を展開したい場合はClaude CodeのGitHub Actionsを組織全体に導入する手順も参考にしてください。GitHub Actions以外のワークフロー基盤をClaude Codeで書く例は、Claude CodeでPrefectのワークフローを書く記事にまとめています。