同一リポジトリ内のActionを呼び出すためだけに、actions/checkoutとuses: ./.github/actions/...を組み合わせている場合は、GitHub Actionsの新しい「$/」構文へ移行できます。
2026年7月30日からgithub.comで利用可能になった自己リポジトリ参照構文で、uses: $/.github/actions/...のように記述すると、ワークフローが実行されている正確なコミットにあるActionやReusable Workflowが参照されます。Actionを読み込むためのcheckoutは不要です。ただし、Self-hosted Runnerではバージョン2.336.0以降が必要なため、古いRunnerを使用している環境では先に更新しなければなりません。(The GitHub Blog)
2026年9月3日には、再利用ワークフロー自身のリポジトリやコミットを取得する job.workflow_* も追加されました。Actionを呼ぶなら $/、同居する一般スクリプトを取り出すなら job.workflow_repository と job.workflow_sha をcheckoutへ渡す、という使い分けができます。GitHubの9月更新案内を踏まえ、まず新しい識別情報の使い方を説明します。
再利用ワークフロー自身を参照するjob.workflow_*
別リポジトリから呼ばれた再利用ワークフローでは、呼び出し元のアプリケーションと、ジョブを定義する共通ワークフローの保存先が異なります。次の4項目は、現在のジョブを定義しているワークフローの情報を返します。
| 項目 | 返す情報 |
|---|---|
job.workflow_ref | 定義ファイルの完全な参照。リポジトリ、ファイルパス、refを含む。 |
job.workflow_sha | そのワークフロー定義のコミットSHA。 |
job.workflow_repository | 定義を保存しているowner/repo。 |
job.workflow_file_path | リポジトリのルートからの定義ファイルの相対パス。 |
github.workflow_ref と github.workflow_sha は呼び出し元を表すため、再利用ワークフローの中ではjob側と異なることがあります。通常のワークフロー内に直接定義したジョブでは、job.workflow_ref と github.workflow_ref は一致します。
たとえばアプリのリポジトリから共通CIのリポジトリを呼ぶ構成では、共通CIのジョブで job.workflow_repository を使うと共通CI側を識別できます。github.repository の既定値のままcheckoutすると、通常は呼び出し元のアプリ側を取得するため、目的に応じて指定を分けます。Contexts referenceに定義とcheckout例が掲載されています。
同居する一般スクリプトを正しいコミットから取り出す
次は、再利用ワークフローと同じリポジトリに scripts/check.sh が置かれている場合の構成例です。repository に定義元のリポジトリ、ref にその定義のSHAを指定します。取得先も workflow-source と明示し、呼び出し元のソースと混ざらないようにします。
name: Shared check
on:
workflow_call:
permissions:
contents: read
jobs:
check:
runs-on: ubuntu-latest
steps:
- name: Show workflow identity
env:
WORKFLOW_REF: ${{ job.workflow_ref }}
WORKFLOW_FILE: ${{ job.workflow_file_path }}
run: |
printf '%s\n' "$WORKFLOW_REF"
printf '%s\n' "$WORKFLOW_FILE"
- name: Checkout workflow source
uses: actions/checkout@v7
with:
repository: ${{ job.workflow_repository }}
ref: ${{ job.workflow_sha }}
path: workflow-source
persist-credentials: false
- name: Run colocated script
run: bash workflow-source/scripts/check.shこの例のスクリプト名は説明用です。実際にそのコミットへ保存されているパスに合わせて変更します。@v7 はcheckoutの参照例で、フル長SHA固定を要求する環境では確認済みの対応SHAに置き換えてください。コードは構成例であり、個別のリポジトリでの実行結果を保証するものではありません。
呼び出し元のアプリも必要なら、別のcheckoutを path: caller-source などへ配置し、ビルドやテストでどちらを参照するか指定します。checkoutの path はワークスペース配下の保存先です。actions/checkoutの公式READMEでは複数リポジトリの配置例とアクセス条件を確認できます。
識別情報を得ても、privateリポジトリの権限は増えない
新しいjobコンテキストは定義元を識別する機能で、アクセス権を付与する機能ではありません。既定の GITHUB_TOKEN は呼び出し元のリポジトリを基準にした権限であり、別のprivate・internalリポジトリをcheckoutできるとは限りません。
共通リポジトリへの読取権限が必要な構成では、組織の方針に沿って対象を限定した資格情報を用意し、checkoutの token などへ渡します。再利用ワークフロー側でも必要なsecretを宣言して受け渡します。参照先の識別が正しいのに認証が失敗する場合は、repository/refを呼び出し元へ戻してごまかさず、対象リポジトリの権限を確認してください。
$/との使い分けと利用できない環境
| 目的 | 使うもの |
|---|---|
| 同じリポジトリのAction・再利用ワークフローを呼ぶ | uses: $/...。呼び出す定義を同じコミットでそろえる。 |
| ジョブの定義元リポジトリとコミットを取得する | job.workflow_repository と job.workflow_sha。checkoutの入力にも利用する。 |
| ワークスペースにある一般ファイルを実行する | checkoutなどでファイルを配置し、run でそのパスを指定する。 |
$/ を run: $/scripts/check.sh のような一般パスとして使うことはできません。また job.workflow_file_path はワークフロー定義の位置であり、そのファイルを自動でワークスペースへ配置する値ではありません。
この4つの job.workflow_* はGitHub Enterprise Serverでは利用できません。$/ もgithub.com向けで、必要なRunnerバージョンは2.336.0以降です。これらを追加する前に提供環境とRunnerを確認します。以下の $/ の基本例や移行手順も、これらの条件を前提にしています。
GitHub Actionsの「$/」自己リポジトリ構文とは
GitHub Actionsの「$/」は、実行中のWorkflowまたはActionと同じリポジトリを表す自己リポジトリ参照です。
たとえば、次の記述は、実行中のコミットにある.github/actions/setup-projectを呼び出します。
- name: Set up project
uses: $/.github/actions/setup-project$/はシェル変数やGitHub Actionsの式ではありません。uses:で使用する専用の接頭辞です。
重要なのは、デフォルトブランチの最新版ではなく、実行中のWorkflowと同じコミットへ解決される点です。WorkflowとActionを同じコミットで変更した場合も、呼び出し元と呼び出し先の内容がずれにくくなります。(GitHub Docs)
同一リポジトリのActionを呼び出す主な方法は、次の3つです。
| 構文 | 参照先・用途 | Action参照前のcheckout |
|---|---|---|
$/path/to/action | 定義元と同じリポジトリ・実行コミットのAction | 不要 |
./path/to/action | ワークスペース上のAction。配置した内容を参照する場合 | 必要 |
owner/repository@ref | 指定したリポジトリとrefのAction | 不要 |
GitHubは、同一リポジトリ内のActionやReusable Workflowを構成する場合、$/を推奨しています。(GitHub Docs)
同一リポジトリのActionを「$/」で参照する方法
次のようなリポジトリ構成を例にします。
sample-project/
├─ .github/
│ ├─ workflows/
│ │ └─ ci.yml
│ └─ actions/
│ └─ setup-project/
│ └─ action.yml
├─ src/
└─ package.json.github/actions/setup-project/action.ymlには、カスタムActionの定義を記述します。
name: Setup project
description: Prepare the project environment
inputs:
node-version:
description: Node.js version
required: false
default: "24"
runs:
using: composite
steps:
- name: Show selected version
shell: bash
run: echo "Node.js version is ${{ inputs.node-version }}"カスタムActionのディレクトリには、メタデータファイルとしてaction.ymlまたはaction.yamlが必要です。GitHubではaction.ymlが推奨されています。(GitHub Docs)
Workflow側では、次のように$/から始まるパスを指定します。
name: CI
on:
push:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Run repository action
uses: $/.github/actions/setup-project
with:
node-version: "24"このActionを読み込むだけであれば、事前のactions/checkoutは必要ありません。$/はRunnerのワークスペースではなく、実行中のコミットにあるリポジトリを直接参照するためです。(GitHub Docs)
checkoutが完全に不要になるわけではない
$/によって不要になるのは、同一リポジトリのActionを見つけるためだけに実行していたcheckoutです。
ビルド、テスト、静的解析などでリポジトリのソースコードを$GITHUB_WORKSPACEへ配置する必要がある場合は、引き続きactions/checkoutが必要です。actions/checkoutは、リポジトリをRunnerの$GITHUB_WORKSPACEへ配置するActionだからです。(GitHub)
jobs:
build:
runs-on: ubuntu-latest
steps:
# 実際には信頼できるフル長SHAへ置き換える
- name: Checkout source
uses: actions/checkout@<FULL_LENGTH_COMMIT_SHA>
- name: Run repository build action
uses: $/.github/actions/build-project次のように判断すると、checkoutを削除しすぎる失敗を防げます。
| Workflowの処理 | checkout |
|---|---|
| 同一リポジトリのActionを呼ぶだけ | 原則不要 |
npm testやdotnet buildなどでソースを使用する | 必要 |
git diffやgit logを実行する | 必要 |
| Action自身のディレクトリに同梱したスクリプトだけを使う | 構成によっては不要 |
| ワークスペース上の設定ファイルや成果物を参照する | 必要 |
Composite Action内でも「$/」を利用できる
$/は通常のWorkflow Stepだけでなく、Composite Action内のuses:でも利用できます。複数の社内Actionを組み合わせたネスト構成にも対応しています。(The GitHub Blog)
たとえば、.github/actions/ci/action.ymlから、同じリポジトリ内にある2つのActionを呼び出せます。
name: Repository CI
description: Run the standard CI process
runs:
using: composite
steps:
- name: Set up project
uses: $/.github/actions/setup-project
- name: Run lint
uses: $/.github/actions/run-lint
- name: Run tests
uses: $/.github/actions/run-testsWorkflow側では、上位のComposite Actionだけを呼び出します。
jobs:
ci:
runs-on: ubuntu-latest
steps:
- name: Run repository CI
uses: $/.github/actions/ciこの構成では、ci、setup-project、run-lint、run-testsがすべて実行中のコミットにそろいます。
従来のように、内部Actionごとにowner/repository@mainや個別のSHAを記述する必要がありません。Actionの階層が深くなっても、コミットの整合性を保ちやすくなります。
別リポジトリから呼び出された場合の解決先
$/は、常にその記述が置かれているファイルのリポジトリを基準に解決されます。
たとえば、アプリケーションリポジトリから共通CIリポジトリのReusable Workflowを呼び出し、そのReusable Workflow内に$/が書かれている場合、参照先はアプリケーションリポジトリではありません。Reusable Workflowが保存されている共通CIリポジトリです。(GitHub Docs)
application-repo
└─ 共通CIのReusable Workflowを呼び出す
automation-repo
├─ .github/workflows/ci.yml
└─ .github/actions/setup/action.ymlautomation-repoのci.ymlに次の記述がある場合、
- uses: $/.github/actions/setup参照されるのはautomation-repoの.github/actions/setupです。
この仕様により、共通Workflowと、その内部で使用するActionを一つのリポジトリにまとめやすくなります。
Reusable Workflowを「$/」で呼び出す方法
同一リポジトリ内のReusable Workflowも、$/で参照できます。
呼び出し元のWorkflowでは、jobs.<job_id>.usesに次のように指定します。
name: Main CI
on:
push:
pull_request:
jobs:
call-reusable-test:
uses: $/.github/workflows/reusable-test.yml
with:
node-version: "24"
secrets: inherit呼び出される.github/workflows/reusable-test.ymlは、次のように定義できます。
name: Reusable test
on:
workflow_call:
inputs:
node-version:
description: Node.js version
required: true
type: string
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Set up project
uses: $/.github/actions/setup-project
with:
node-version: ${{ inputs.node-version }}この例では、Reusable Workflowだけでなく、その中から呼び出すComposite Actionにも$/を利用しています。すべて実行中の同じコミットに解決されます。(GitHub Docs)
「$/」には@mainや@SHAを付けない
$/は実行中のコミットへ自動的に解決されるため、末尾に@main、@v1、@SHAなどを付けてはいけません。
次の記述は無効です。
- uses: $/.github/actions/setup-project@mainReusable Workflowでも同様です。
jobs:
test:
uses: $/.github/workflows/reusable-test.yml@main正しくは、@refを付けずに記述します。
- uses: $/.github/actions/setup-projectjobs:
test:
uses: $/.github/workflows/reusable-test.ymlまた、Reusable Workflowを指定するjobs.<job_id>.usesでは、コンテキストや式を使ってパスを動的に組み立てることはできません。(GitHub Docs)
フル長SHA固定ポリシーと両立する理由
GitHub Actionsでは、第三者Actionをフル長のコミットSHAへ固定することが、改ざんや予期しない更新への対策として推奨されています。GitHub Enterprise Cloudには、Actionをフル長SHAへ固定するよう強制するポリシーもあります。(GitHub Docs)
従来、共通リポジトリのReusable WorkflowをSHA固定していても、その内部で次のような参照を使っていると、バージョンがずれる可能性がありました。
# 共通Workflow自体はSHA固定されている
jobs:
common-ci:
uses: example-org/automation/.github/workflows/ci.yml@<FULL_LENGTH_COMMIT_SHA>共通Workflow内で内部Actionを@main参照していた場合、呼び出し元が固定したコミットとは異なるActionが実行される可能性があります。
# 同じリポジトリだが、mainの最新版を参照してしまう
- uses: example-org/automation/.github/actions/setup@main$/を使えば、内部ActionもReusable Workflowと同じコミットになります。
- uses: $/.github/actions/setupこれにより、呼び出し元が共通Workflowをフル長SHAへ固定した場合、そのWorkflow内の同一リポジトリ参照も同じコミットにそろいます。GitHubは、$/がフル長SHA固定を要求するEnterpriseポリシーと両立すると説明しています。(The GitHub Blog)
ただし、$/は外部ActionのSHA固定を代替するものではありません。
steps:
# 同一リポジトリ
- uses: $/.github/actions/setup
# 外部リポジトリ
- uses: third-party/example-action@<FULL_LENGTH_COMMIT_SHA>同一リポジトリは$/、外部リポジトリは検証済みのフル長SHAという形で使い分けるのが基本です。
Self-hosted Runnerは2.336.0以降が必須
GitHub Actionsの$/構文を実行するには、GitHub Actions Runner 2.336.0以降が必要です。特に、Self-hosted Runnerを管理している組織では、Workflowを変更する前にRunnerのバージョンを確認してください。(The GitHub Blog)
Runnerのインストールディレクトリでは、次のようにバージョンを確認できます。
LinuxまたはmacOSの場合：
./config.sh --versionWindowsのPowerShellの場合：
.\config.cmd --versionRunnerのコマンドには、バージョンを表示する--versionオプションが用意されています。(GitHub)
Self-hosted Runner更新前の確認項目
| 確認項目 | 判断基準 |
|---|---|
| Runnerバージョン | 2.336.0以上 |
| 自動更新 | 無効化していないか |
| コンテナイメージ | 古いRunnerを固定していないか |
| Runnerグループ | 一部のRunnerだけ古くないか |
| GitHubの提供形態 | github.comか、GitHub Enterprise Serverか |
| 更新後の確認 | $/を使った最小Workflowが成功するか |
Self-hosted Runnerは標準では自動更新されます。ただし、登録時に--disableupdateを指定している場合や、Runnerをコンテナイメージへ固定している場合は、運用者側で更新が必要です。
GitHubのドキュメントでは、新機能がRunner側の変更を必要とすることがあるため、手動更新を選択している場合もRunnerを定期的に更新するよう案内しています。自動更新を無効化したRunnerは、新しいバージョンの公開後30日以内に更新する必要があります。(GitHub Docs)
複数のRunnerがある場合は全台確認する
同じWorkflowでも、実行時に選ばれたRunnerによって結果が変わる状態は避けなければなりません。
たとえば、Runnerグループ内に次の2台がある場合です。
runner-01 2.336.0
runner-02 2.335.1runner-01では成功しても、runner-02では$/を処理できない可能性があります。
リポジトリ、Organization、EnterpriseのSettingsからActions、Runnersを開き、対象となるRunnerの名前、ラベル、オンライン状態を洗い出してください。Runnerの更新ログは、インストールディレクトリの_diagにあるRunner_ログやSelfUpdateログから確認できます。(GitHub Docs)
「./」から「$/」へ安全に移行する手順
既存Workflowを一括置換する前に、次の順序で移行するとトラブルを減らせます。
利用環境を確認する
最初に、対象環境がgithub.comであることを確認します。
$/構文は、現時点ではGitHub Enterprise Serverでは利用できません。GitHub Enterprise Serverを使用している場合は、従来の./またはowner/repository@refを継続する必要があります。(GitHub Docs)
Self-hosted Runnerについては、2.336.0以上へ更新します。
既存のローカル参照を検索する
リポジトリ内でuses: ./を使用している箇所を検索します。
git grep -n "uses: ./" -- .github検索結果では、主に次の2種類を確認します。
uses: ./.github/actions/exampleuses: ./.github/workflows/reusable.yml外部リポジトリをcheckoutした後、そのディレクトリ内のActionを./で呼び出している特殊な構成は、機械的に置換してはいけません。
同一リポジトリ参照だけを置き換える
Actionの場合：
# 変更前
- uses: ./.github/actions/setup-project
# 変更後
- uses: $/.github/actions/setup-projectReusable Workflowの場合：
# 変更前
jobs:
test:
uses: ./.github/workflows/reusable-test.yml
# 変更後
jobs:
test:
uses: $/.github/workflows/reusable-test.ymlcheckoutの用途を確認する
actions/checkoutを削除する前に、後続処理を確認します。
次のような処理がある場合は、checkoutを残します。
- run: npm ci
- run: npm test
- run: dotnet build
- run: git diff --exit-code
- run: ./scripts/build.shcheckout後にローカルActionを呼び出しているだけで、ほかにリポジトリのファイルを使用していない場合は、checkoutを削除できる可能性があります。
ブランチ上で動作確認する
最初からすべてのWorkflowを変更せず、利用頻度の低いWorkflowまたは検証用ブランチで確認します。
確認すべき内容は次のとおりです。
- Workflow Stepから同一リポジトリActionを呼び出せるか
- Composite Action内の
$/が解決されるか - Reusable Workflowを呼び出せるか
- Self-hosted Runnerで成功するか
- checkout削除後も必要なソースファイルが存在するか
- WorkflowとActionを同じコミットで変更した結果が反映されるか
外部Actionの参照方法も監査する
./を$/へ移行する作業とあわせて、外部Actionがブランチや可変タグへ固定されていないか確認します。
# 同一リポジトリ
- uses: $/.github/actions/setup
# 外部リポジトリは検証済みのフル長SHA
- uses: example-org/example-action@<FULL_LENGTH_COMMIT_SHA>$/によって内部参照の整合性を高めても、外部Actionを@mainなどで参照していれば、サプライチェーン上のリスクは残ります。(GitHub Docs)
GitHub Actionsの「$/」で失敗しやすいポイント
Runnerを更新せずにWorkflowだけ変更する
Self-hosted Runner 2.335.1以前では、新構文を正常に処理できません。
先にRunnerを2.336.0以上へ更新し、すべてのRunnerグループでバージョンがそろっていることを確認してからWorkflowを変更します。
「$/」の末尾にrefを付ける
次の記述はできません。
uses: $/.github/actions/setup@main$/は実行中のコミットへ自動解決されるため、@main、@v1、@SHAは不要です。
checkoutをすべて削除する
$/を使えばActionの参照にcheckoutは不要ですが、ソースコードを使う処理ではcheckoutが必要です。
「Actionの読み込み」と「リポジトリのソースをRunnerへ配置する処理」を分けて考えてください。
呼び出し元リポジトリを参照すると誤解する
Reusable WorkflowやComposite Actionが別リポジトリから呼び出されている場合、$/は呼び出し元ではなく、$/が記述されたファイルのリポジトリを参照します。(GitHub Docs)
GitHub Enterprise Serverで使用する
$/はgithub.com向けの機能です。GitHub Enterprise Serverでは利用できません。
同じWorkflowをgithub.comとGitHub Enterprise Serverの両方で運用している場合、共通ファイルをそのまま共有できない可能性があります。移行前に実行環境を分けて確認してください。
「$/」だけでWorkflowが安全になると考える
$/は、同一リポジトリ内の参照先を実行中のコミットへそろえる機能です。Workflowの権限設定や、信頼できないPull Requestからのコード実行を自動的に安全にする機能ではありません。
GITHUB_TOKENの権限を必要最小限にし、Workflowや.github/actionsへの変更をレビュー対象にするなど、従来のセキュリティ対策も継続してください。特にSelf-hosted Runnerでは、信頼できないコードを実行した場合の影響が大きくなるため注意が必要です。(GitHub Docs)
まとめ
GitHub Actionsの$/自己リポジトリ構文を使うと、同一リポジトリにあるActionやReusable Workflowを、実行中の正確なコミットから参照できます。
従来の./と異なり、Actionを読み込むためだけのcheckoutは不要です。Workflow Step、Composite Action、ネストされたAction構成、Reusable Workflowの呼び出しに利用でき、フル長SHA固定ポリシーとも両立します。
移行時は、次の順序で進めるのが安全です。
- github.comで実行していることを確認する
- Self-hosted Runnerを2.336.0以上へ更新する
git grep -n "uses: ./" -- .githubで既存参照を洗い出す- 同一リポジトリ参照を
$/へ変更する - ソースコードを使う処理ではcheckoutを残す
- Composite ActionとReusable Workflowを含めて動作確認する
- 外部Actionは引き続き検証済みのフル長SHAへ固定する
まずは一つのWorkflowで./.github/actions/...を$/.github/actions/...へ置き換え、Runnerのバージョンとcheckoutの必要性を確認してから、ほかのWorkflowへ展開するとよいでしょう。
一般スクリプトも共通ワークフローと同じコミットへそろえたい場合は、job.workflow_repository と job.workflow_sha をcheckoutへ指定し、job.workflow_ref と job.workflow_file_path で取得対象を確認してください。$/ とjobコンテキストを目的ごとに使い分けることで、呼び出し元のソースとの取り違えを防げます。
コメント