tea-e7n.dev

GitHub Actionsの$/記法について知る

GitHub Actionsのworkflowから同一リポジトリ内のactionを参照する場合、従来はactions/checkoutを利用した上で、./xxx形式のpath指定を行うことで参照することができました。 また、checkoutを避ける場合には、リポジトリ名とrefを明示的に指定して参照することも可能となっていました。

しかし先日のアップデートにより$/というシンタックスが新たに導入され、checkoutやref指定なしに同一リポジトリ内のactionを実行することが可能になりました。

ここでは、その利用方法について簡単に見ていこうと思います。

セットアップ

まずはworkflow内から利用されるactionを適当に定義します。

.github/actions/github-actions-self-repository/message.txt
message-from-self-repository-action
.github/actions/github-actions-self-repository/action.yml
name: Read bundled message
description: Read a message bundled with this composite action.

outputs:
  message:
    description: The message read from message.txt.
    value: ${{ steps.read-message.outputs.message }}

runs:
  using: composite
  steps:
    - id: read-message
      name: Read message from the action directory
      shell: bash
      run: |
        set -euo pipefail
        message="$(<"$GITHUB_ACTION_PATH/message.txt")"
        printf 'message=%s\n' "$message" >> "$GITHUB_OUTPUT"

$/構文を使ってみる

次のworkflowを定義します。

.github/workflows/github-actions-self-repository.yml
name: Verify GitHub Actions self-repository syntax

on:
  pull_request:
    paths:
      - .github/workflows/github-actions-self-repository.yml
      - .github/actions/github-actions-self-repository/**
  push:
    paths:
      - .github/workflows/github-actions-self-repository.yml
      - .github/actions/github-actions-self-repository/**

permissions:
  contents: read

jobs:
  local-action:
    name: ./ reference with checkout
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - id: local-action
        uses: ./.github/actions/github-actions-self-repository

      - run: test "${{ steps.local-action.outputs.message }}" = "message-from-self-repository-action"

  self-repository-action:
    name: $/ reference without checkout
    runs-on: ubuntu-latest
    steps:
      - id: self-action
        uses: $/.github/actions/github-actions-self-repository

      - run: test "${{ steps.self-action.outputs.message }}" = "message-from-self-repository-action"

やっていることは、セットアップで定義したactionを、従来通りcheckoutを利用して実行するjobと、checkoutを利用せず$/構文を利用して実行するjobを並べているだけです。

各々のjobが正常に終了すれば、問題なく動作しているということが確認できていることになります。

実行した結果は以下の通りです。

checkoutありバージョン
$/構文バージョン

$/構文バージョンでは、確かにcheckoutなしでも動いていることがわかります。

またもう一つの特徴として、$/構文を利用した場合には、利用対象のactionに対してcommit hashを自動的に解決していることがわかります。 このcommit hashは、呼び出し元が参照するcommit hashと同一のものとなっています。

$/構文のメリット・デメリットと制約

メリット

  • actionの参照だけを目的としたcheckoutをスキップできる
  • 呼び出されるactionは呼び出し元と同じcommitを自動的に参照するため、意図しないバージョン不一致を防ぎやすい

デメリット

  • 特になし

制約

  • 2026-08-29現在、GitHub.com専用であり、GitHub Enterprise Serverでは利用不可
  • Runner 2.336.0以上が必要

まとめ

$/という新たな構文を利用することで、checkout・ref指定不要な形で同一リポジトリ上のactionを利用することができます。

これにより、意図しないバージョン不一致を防いだり、checkoutにかかる時間を短縮できることが期待できます。