GitHub ActionsのReusable WorkflowでSecretが空になるときの確認

Reusable Workflowを呼ぶと、認証に使うsecretだけが空になる。まず調べるのは、secretの作成し直しではなく、呼び出し元が何を渡し、呼び出し先のどのjobが何を読むかです。通常のworkflowで読めた値も、再利用workflowへ自動的に同じ形で届くとは限りません。

この記事では、callerからcalled workflowへのsecret受渡しと、environment secretの選択を分けて確認します。stepやjobのoutputsをcallerへ返す問題とは方向も契約も違います。秘密値をoutputへ載せて回避する方法は使いません。

名前と受渡しの場所を一枚にする

失敗したrunのworkflow revisionを固定し、呼出jobのuses、secrets指定、呼出先jobのenvironment、secretを使うstepを順に確認します。現在のmainだけを見ると、失敗時とは違う設定を読んでしまう場合があります。

表は横にスクロールできます

境界	確認するもの	記録例の意味
保管先	repository・organization・environment	同名が複数の場所にあるか
callerの呼出job	secretsの名前付きmap、またはinherit	どの値を受け渡す契約か
called workflow	workflow_callのsecret定義と参照名	呼出側の名前とつながるか
実行job	environmentと利用step	どの環境の値を使うか

GitHub公式の再利用workflow資料は、secretを呼出元から渡し、呼出先で参照する方法を案内しています。名前付きで渡す場合は、caller側のキーと呼出先が読むsecret名を照合します。同一organizationやenterprise内で利用できるinheritもありますが、原因が分からないまま一律に受渡しを広げる必要はありません。GitHub：Reuse workflows（新しいタブで開く）

environmentの指定だけで完了と判断しない

2026年10月20日時点の公式資料では、environment secretを再利用workflowで使う場合、呼出先jobにenvironmentを設定し、callerからもsecretを渡すと説明しています。再利用workflowを呼ぶ側のjobへenvironmentを書く方法とは分けて確認してください。

同じ名前のrepository／organization secretとenvironment secretがあると、対象environmentを持つjobではenvironment側が優先される扱いです。「値を更新したのに変わらない」ときは、更新した保管先と、実行jobが選んだenvironmentが合っているかを見ます。別の環境へ切り替えて認証を通すと、意図しない接続先へ処理するおそれがあります。

必要なsecretにrequiredを指定したことも、値が非空で正しいことの保証にはなりません。公式資料は、requiredが受渡しの指定を検査するもので、値そのものの存在確認とは違うと注意しています。呼出しの成立、値の提供条件、認証先での有効性を別に確認します。GitHub：Workflow syntax（新しいタブで開く）

AからBへ渡せても、Cまで届いたとは限らない

再利用workflowをさらに呼ぶ場合、経路ごとにsecretの受渡しを確認します。最初のcallerでinheritを使っていても、途中のworkflowが次へ渡していなければ、末端で読む前提にできません。

以下は架空の設計表です。実行結果ではありません。credentialの値は記録せず、名前と必要な利用先だけを整理します。

表は横にスクロールできます

呼出経路	必要なsecret名	確認する指定
A → B	SERVICE_TOKEN	Aの呼出jobとBの受取名
B → C	SERVICE_TOKEN	BからCへの明示的受渡し
Cの実行job	SERVICE_TOKEN	environment・利用step・認証先

一つの呼出しを修正したら、次の境界へ進む前に結果を確認します。全段へinheritを足すと、どの境界に不足があったか分かりにくくなります。外部repositoryの再利用workflowを呼ぶ場合は、参照revisionと、渡すsecretをそのworkflowが必要とする理由も確認してください。

保存時点と実行時点を混同しない

GitHubのSecrets referenceは、organization／repository secretをrunのqueue時、environment secretを対象jobの開始時に読むと説明しています。更新前にqueueへ入ったrunと、更新後に開始したjobでは、確認すべき時点が同じとは限りません。GitHub：Secrets reference（新しいタブで開く）

記録にはsecretの更新時刻、runの作成時刻、対象jobの開始時刻を残します。既に失敗したrunの画面だけで「今も新しい値が読めない」と判断せず、許可された検証環境でどの時点の設定を使ったか確かめます。secret値やその一部をログへ出す必要はありません。

空になる原因と、認証が拒否される原因を分ける

fork PR等でsecret自体が提供されない条件、callerの受渡し不足、environmentの取り違えを先に確認します。値が提供される経路を確認できた後に、失効・接続先・認証方式を調べます。認証エラーだけを理由に、すべてのsecretを別scopeへ複製しないでください。

表は横にスクロールできます

観察した状態	先に見る箇所	避ける回避
再利用化した後だけ空	callerとcalleeの契約	outputやartifactで秘密を運ぶ
environment別で結果が違う	environment名と同名secretの保管先	本番の値を検証環境へ複製する
入れ子の末端だけ空	途中の各呼出job	全段の権限を一律に広げる
値は提供されるが認証失敗	認証先・期限・必要scope	受渡しの問題だと決めつける

完了条件は、どのscopeからどのjobへ渡り、どの呼出境界が原因だったか説明できることです。実行確認には機密を持たないテスト値と許可された環境を使い、本番接続の成功を未実施のまま報告しないでください。この記事ではworkflowの実行やsecretの作成・更新は行っていません。