公開2026.08.25更新2026.09.27 GitHub

GitHub Actionsの手動実行（workflow_dispatch）｜inputsの型定義とCLI・APIからの起動

GitHub Actionsで「ボタンを押したときだけ動かす」ワークフローを作るトリガーが workflow_dispatch です。デプロイやデータ移行のように、条件がそろった瞬間に人が判断して流したい処理へ向いています。書き方そのものは数行で済みますが、実務で詰まるのは入力値の型と、画面以外から叩くときの権限、そして repository_dispatch との境界でした。

ここではワークフローの基本構造や他のイベントの選び方には立ち入りません。全体像はGitHub Actionsとは？できること・使い方とCI/CD自動化の解説を、push や pull_request を含む発火条件の設計はGitHub Actionsのトリガー（on）｜イベント選定とbranches・pathsフィルタの設計を参照してください。本記事は人が起こす起動だけを扱います。記載した数値と仕様は2026年8月時点の公式ドキュメントで実測したものです。

まとめ：手動実行を組む前に決める3つの分岐と結論

先に結論を出します。第一に、起動の窓口を画面にするか外部システムにするかで、使うイベントが分かれます。人が画面から起票するなら workflow_dispatch、監視やチケットなど外部の出来事で駆動するなら repository_dispatch です。両方を同じワークフローに書いて併存させることもできます。

第二に、入力をどこまで受けるかを決めます。自由入力の文字列を並べると事故が増えるため、環境名やリリース種別は choice で選択肢に固定し、真偽の切り替えは boolean にします。上限は最上位プロパティ25個・65,535文字で、日本語圏でよく見かける「最大10個」という記述は現行のドキュメントと一致しません。

第三に、誰が何に対して流せるかを縛ります。手動実行は起動時に ref を選べるので、対象のブランチやタグを固定したい場合は入力ではなく ref 側で制御し、本番反映は Environment の承認と組み合わせてください。この3点を先に決めておけば、後からYAMLを書き直す手戻りは避けられます。

workflow_dispatchの基本：既定ブランチ配置と実行するrefの関係

最小の書き方は on の下に workflow_dispatch を置くだけです。入力が不要なら空で構いません。

on:
  workflow_dispatch:

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Run release
        run: echo release

ワークフローファイルが既定ブランチに無いと起動ボタンが出ない仕様

公式ドキュメントは、このイベントについて「ワークフローファイルが既定ブランチに存在する場合にのみワークフロー実行を発生させる」と明記しています。作業ブランチでYAMLを書いた段階では画面に起動ボタンが現れず、設定を疑って時間を溶かしがちな箇所です。まず既定ブランチへマージしてください。マージ後は、起動時に他のブランチを ref として選べるようになります。

同じ制約は定期実行にもかかっており、時刻起動側の詳細はGitHub Actionsの定期実行（cron）｜timezone指定・遅延と欠落・60日停止の実務にまとめています。ボタンが出ないときの切り分けは、既定ブランチにファイルがあるか、on に workflow_dispatch を書いたか、YAMLの構文エラーで無効化されていないか、の3点を順に見る流れが早いです。

起動時に選ぶrefで実行される定義とコードの版が決まる仕組み

起動画面のブランチ選択、あるいは API の ref 指定は、実行されるワークフロー定義とチェックアウト対象の両方を決めます。つまり release/1.4 を選べば、そのブランチ時点のYAMLとコードで走ります。既定ブランチでYAMLを直したつもりでも、古いタグを ref に選ぶと古い手順が動く点は押さえてください。

リリースタグを ref にして流す運用は、再現性の面で扱いやすい形です。タグは動かない前提なので、同じタグを二度流せば同じ手順が再走します。逆に、長命の作業ブランチを ref に選ぶ運用は、いつのコードが本番へ出たのか追いにくくなります。

run-nameで実行一覧へ入力値を出して起票者を追えるようにする

手動実行は「誰が何を指定して流したか」が後から問われます。ワークフロー直下の run-name は github コンテキストと inputs コンテキストを参照できるため、実行一覧の見出しに入力値と起票者を出せます。

run-name: deploy ${{ inputs.target }} by @${{ github.actor }}

on:
  workflow_dispatch:
    inputs:
      target:
        description: 'デプロイ先'
        type: choice
        required: true
        default: staging
        options:
          - staging
          - production

この一行があるだけで、障害時に実行履歴を遡る速度が変わります。名前だけが並ぶ一覧から該当の実行を探す作業がなくなるためです。

inputsの型定義：choice・boolean・environmentの使い分け

入力の型は description・default・required・type・options で組み立てます。公式のワークフロー構文で規定された type は boolean、choice、number、environment、string のいずれかです。画面に出る入力部品が変わるのは choice、boolean、environment の3種で、ここを使い分けると入力ミスを構造的に減らせます。

type	画面の見え方	受け取る値
string	1行の自由入力	文字列
choice	optionsの選択肢	選ばれた文字列
boolean	チェックボックス	真偽値
environment	環境名の一覧	環境名の文字列
number	公式は型として掲載	検証は自前で用意

choiceでoptionsを列挙して入力値の候補を画面側で固定する

choice は options に書いた値だけを選ばせる型です。デプロイ先、リリース区分、対象リージョンのように語彙が決まっているものは、文字列の自由入力にせず choice へ寄せてください。打ち間違いをジョブ内の条件分岐で弾く必要がなくなり、YAMLから「どの値が正しいのか」を読み取れる利点もあります。

選択肢が環境ごとに増減するケースでは、options をベタ書きすると更新漏れが出ます。その場合は入力を粗く保ち、細部はリポジトリ変数から引く設計へ寄せます。変数と秘密情報の置き分けはGitHub Actionsの環境変数｜env・vars・secretsの使い分けと受け渡しを参照してください。

booleanはinputsコンテキストなら真偽値のまま受け取れる

boolean で気をつけるのは受け取り側です。公式は、ワークフローが inputs コンテキストと github.event.inputs の両方で入力を受け取るとしたうえで、inputs コンテキストは真偽値を文字列へ変換せず真偽値のまま保つ、と説明しています。つまり github.event.inputs 経由では ‘true’ という文字列になり、素朴に比較すると意図しない分岐になります。文字列と真偽値が一致しない理由はGitHub Actionsの条件分岐（if）｜書く場所で変わるコンテキストと評価の規則で解説しました。

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Real run only
        if: inputs.dry_run == false
        run: ./scripts/deploy.sh

新規に書くなら inputs 参照へ統一してください。既存のワークフローを引き継いだ場合は、github.event.inputs のまま文字列比較しているコードが残っていないか確認します。dry_run のような安全弁ほど、この取り違えが本番反映へ直結します。

environment型でリポジトリの環境一覧から選ばせる指定方法

environment 型は、リポジトリに定義済みの環境名を一覧から選ばせる入力です。受け取る値は環境名の文字列なので、ジョブ側の environment キーへ渡してレビュー担当者の承認や環境ごとの秘密情報と結び付けられます。

on:
  workflow_dispatch:
    inputs:
      env_name:
        type: environment
        required: true

jobs:
  apply:
    runs-on: ubuntu-latest
    environment: ${{ inputs.env_name }}
    steps:
      - run: echo apply

ただし、入力で環境を選ばせる形は「本番を選べる人」を画面側で絞れません。承認者や待機時間といった保護ルール自体は環境の設定側にあります。誰でも production を選べる状態が困るなら、入力の選択肢を絞るのではなく、環境の保護ルールで止める設計にします。承認者の指定やデプロイ可能ブランチの縛り方はGitHub ActionsのEnvironments｜承認ゲートと環境別シークレットの設計にまとめています。

inputsの上限は25個と65,535文字で最大10個の記述は古い

公式ドキュメントは inputs の最上位プロパティ数の上限を25、ペイロードの上限を65,535文字と記載しています。REST API側のリファレンスも inputs のプロパティ数上限を25と示しており、記述は一致します。日本語の解説記事には「最大10個」と書かれたものが今も多く残っていますが、これは過去の値です。上限を根拠に設計を削る前に、現行値を確認してください。

とはいえ25個まで並べてよい、という話ではありません。手動実行の入力が10個を超える時点で、その作業は画面から流すには複雑すぎます。設定ファイルをリポジトリへ置いて入力を1〜2個に減らすか、そもそも自動トリガーへ寄せるかを検討する分岐点として使えます。

画面以外からの起動：gh CLIとREST APIで叩く手順と権限

手動実行は画面専用ではありません。同じイベントを CLI と REST API から起こせるため、運用担当者が使う入口を画面に置きつつ、社内の運用ツールからも同じワークフローを叩けます。

gh workflow runの-fと-Fとrefでコマンドから起動する手順

GitHub CLI では gh workflow run を使います。ワークフローはファイル名または名前で指定し、ref でブランチやタグを選びます。

gh workflow run deploy.yml --ref release/1.4 -f target=production -f dry_run=false

echo '{"target":"production","dry_run":false}' | gh workflow run deploy.yml --json

ここに実装上の落とし穴があります。gh workflow run のマニュアルでは -f が –raw-field、-F が –field に割り当てられており、@ 記法を解釈するのは -F の側です。gh api コマンドの同名フラグとは割り当てが逆なので、他のコマンドの記憶で書くと値がファイル読み込みとして扱われたり、その逆になったりします。引数を並べる前に、対象コマンドのヘルプで確認する癖をつけてください。入力が多いときは –json で標準入力からまとめて渡す書き方が読みやすいです。

REST APIのdispatchesを叩くときに要る権限と応答の中身

API から起こす場合のエンドポイントは POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches です。workflow_id にはファイル名を渡せます。ref は必須で、inputs は任意です。

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/deploy.yml/dispatches \
  -d '{"ref":"main","inputs":{"target":"production"}}'

権限は、従来型の個人アクセストークンなら repo スコープが要ります。細粒度のトークンで必要なのは Actions への書き込み権限です。GITHUB_TOKEN側のスコープ設計はGitHub Actionsのpermissions｜GITHUB_TOKENの既定権限と最小権限の設計に整理しました。応答については、実行IDとURLを含む形が現行のリファレンスに示されています。かつては起動できても実行IDが返らず、直後に実行一覧を取得して自分の起動を探し当てる回避策が広く使われていた箇所です。既存の運用ツールにその突き合わせ処理が残っているなら、簡素化できないか見直す価値があります。

GITHUB_TOKENのpushが実行を作らない制限の例外である点

GitHub Actions には、GITHUB_TOKEN で行った push や PR 作成が新しいワークフロー実行を作らないという制限があります。無限ループを避けるための仕様ですが、ワークフローから次のワークフローを起こしたい場面では壁になります。この制限の例外として扱われるのが workflow_dispatch と repository_dispatch です。

そのため、ジョブの中から別のワークフローを起こす構成では、コミットを介して連鎖させるのではなく、明示的に dispatch を叩く形が素直です。同一リポジトリ内で処理を分割したいだけなら、呼び出し関係を型として書けるReusable Workflowsとは？GitHub Actionsのworkflow_callで再利用する方法の方が管理しやすい場面もあります。実行環境そのものを入力で切り替えたい場合はGitHub Actionsのruns-on｜ラベル指定の記法と-latest更新・arm64への備えを併読してください。

repository_dispatchとの使い分け：外部から起動する境界

外部から起こすもう一つのイベントが repository_dispatch です。名前が似ているため混同されますが、想定している起点が違います。

event_typeは100文字・client_payloadは上位10個までの制限

repository_dispatch は event_type で種類を分け、client_payload で任意のデータを渡します。公式では event_type は100文字まで、client_payload の最上位プロパティは10個まで、ペイロード全体は65,535文字までという規定です。workflow_dispatch と違い、入力の型や選択肢という概念はなく、受け取った JSON をワークフロー側で解釈します。

on:
  repository_dispatch:
    types: [deploy-requested]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: echo "${{ github.event.client_payload.version }}"

このイベントも、ワークフローファイルが既定ブランチに存在する場合にのみ発火します。加えて ref を選ぶ仕組みがないため、既定ブランチの定義で走る前提になります。特定のタグの内容で流したいなら workflow_dispatch を選んでください。

画面から人が流すのか外部イベントで駆動するのかを分ける設計基準

境界の引き方は単純です。起点が人の判断で、実行のたびに条件を選ぶなら workflow_dispatch。起点が外部システムの出来事で、渡すデータが構造化された JSON なら repository_dispatch。前者は入力の型と選択肢で守り、後者はペイロードの検証をワークフローの先頭で行います。

両方を on に併記して、画面からも外部からも起こせるようにする構成も取れます。その場合は、入力の取り出し方が inputs と github.event.client_payload で分かれるため、先頭のジョブで値を正規化して後続へ渡す形にすると本体が読みやすくなります。

受託開発でリリース作業を手動起動へ切り出すときの設計と判断基準

ここからは、案件でどこまで自動化し、どこを人の起点に戻すかという話です。全自動が常に良いわけではありません。CI/CDとは？仕組み・パイプライン・導入すべき企業の判断基準で整理している通り、統合とテストの自動化と、本番反映の自動化は別の意思決定です。

デプロイの自動化をどこで止めて人の起点へ戻すかを決めるための実務基準

実務でよく落ち着くのは、検証環境までは push で自動、本番反映は workflow_dispatch という形です。理由は業務側の都合にあります。締め日や営業時間、他システムのメンテナンス時間帯といった条件は、リポジトリの状態からは判断できません。マージのタイミングと反映のタイミングを分離しておくと、開発側の流れを止めずに反映だけ待てます。

切り分けの基準は「反映の可否を決める情報がリポジトリの外にあるかどうか」です。外にあるなら手動起動へ切り出し、リポジトリ内で完結するなら自動トリガーのままにします。曖昧なまま全部を手動にすると、押す作業が属人化して運用の負債になります。

入力を増やしすぎず選択肢で固定する設計にまとめる実務上の考え方

手動起動の入力設計は、少ないほど事故が減ります。目安として、入力は3個までに収め、そのうち自由入力の文字列は0個か1個にとどめてください。デプロイ先は choice、確認のみの実行は boolean、対象の版はタグを ref で選ぶ形にすれば、自由入力を使わずに大半の運用が回ります。

入力が増える背景には、たいてい「1本のワークフローで何でもやろうとしている」構造があります。処理系統が違うなら分割してください。共通部分は再利用可能なワークフローへ切り出し、手動起動のファイルは入口として薄く保つと、起票する側の迷いも減ります。

手動実行を採用してよい条件と見送るべき場面の具体的な判断基準

採用してよいのは次の3条件がそろう場合です。第一に、実行の頻度が低く、人の判断が実行可否を左右すること。第二に、入力が選択肢や真偽値で表現でき、自由入力に頼らないこと。第三に、対象の版を ref で固定でき、本番反映は環境の保護ルールで承認を挟めること。この3つを満たすリリース作業は、手動起動へ切り出した方が事故率も追跡性も改善します。

見送るべき場面も明確です。定刻に流す必要があるなら schedule か外部のスケジューラへ寄せます。外部システムの出来事で駆動するなら repository_dispatch です。1日に何度も押す運用になっているなら、それは自動化されるべき処理が人の手に残っているサインなので、トリガーの設計から見直してください。押す人が特定の1名に固定されている状態も、休暇や離職で止まるため見送りの理由になります。

切り出したあとに残るのは、押す手順の文書化と、失敗時の切り戻し、権限の棚卸しといった運用の仕事です。ここを内製で回しきれるかどうかが、手動起動を採用できるかの実質的な条件になります。体制づくりから引き取りまで含めて相談したい場合は、保守運用・内製化支援のページをご覧ください。

よくある質問

画面にRun workflowのボタンが表示されないのはなぜですか？

ワークフローファイルが既定ブランチに存在しないケースが最も多い原因です。公式ドキュメントも、このイベントは既定ブランチにファイルがある場合にのみ実行を発生させると明記しています。作業ブランチで書いた段階では出ません。既定ブランチへマージしたうえで、on に workflow_dispatch を書いたか、YAMLの構文エラーでワークフローが無効になっていないかを順に確認してください。

入力値を数値や真偽値として受け取ることはできますか？

真偽値については、boolean 型の入力を inputs コンテキストで参照すれば真偽値のまま受け取れます。github.event.inputs 経由だと文字列へ変換されるため、条件式が意図せず成立します。数値は type として number を書けますが、値の妥当性検査はワークフロー側で用意する前提で設計してください。

手動実行で古いタグの内容を流すことはできますか？

できます。起動時に選ぶ ref は、実行されるワークフロー定義とチェックアウトされるコードの両方を決めるため、リリースタグを指定すればその時点の手順で再走します。ボタンの表示自体は既定ブランチのファイルに依存する一方、実行対象は ref 側で選べる、という二段構えだと理解しておくと混乱しません。

社内の運用ツールから起動するには何を用意すればよいですか？

REST API の dispatches エンドポイントへ POST するか、gh workflow run を実行します。従来型の個人アクセストークンなら repo スコープ、細粒度のトークンなら Actions への書き込み権限が要ります。監視やチケットの発生を起点にするなら、workflow_dispatch ではなく repository_dispatch を選ぶ方が素直です。