Github ActionsにおけるGITHUB_SHAとGITHUB_REF

はじめに

GitHub Actionsの環境変数を利用したい時にややこしいと感じた為イベントごとにまとめてみました。

GitHub Actionsとは

GitHub Actions は、ビルド、テスト、デプロイのパイプラインを自動化できる継続的インテグレーションと継続的デリバリー (CI/CD) のプラットフォームです。 リポジトリに対するすべての pull request をビルドしてテストしたり、マージされた pull request を運用環境にデプロイしたりするワークフローを作成できます。

Github上でワークフローを作成してそれを様々なタイミングで実行できるCI/CDのプラットフォームです

テストの自動化だったりチームのレビュー運用だったりをカスタマイズできます

GitHub Actionsのイベント

GitHub Actionsの実行をトリガーできるイベントで代表的なものは以下になります

イベント	実行タイミング
push	リポジトリにpushされたとき
pull_reqest	Pull Requestがオープン、更新、クローズされたとき
release	リリースが公開されたとき
schedule	定期的に実行
workflow_dispatch	手動で実行

環境変数

GHAのワークフローでは、以下のように独自に環境変数を定義して使用する事ができます

.yml

env:
    MY_VAR: "my value" # 環境変数を設定
steps:
- name: Example step
  run: echo $MY_VAR # step内で環境変数を使用

ただ、独自に定義する環境変数とは別にGHAでトリガーできる多くのイベントにGITHUB_SHAとGITHUB_REFが設定されています

GITHUB_SHAとGITHUB_REFは以下のような特徴があります

GITHUB_SHA

現在実行中のコミットのSHA値（ハッシュ）を表します
これは、GitHub Actionsがビルド、テスト、デプロイなどのアクションを実行する際に、どのコミットが実行されているかを識別するために使用されます

GITHUB_REF

現在実行中のGitリポジトリのブランチ名、タグ名、またはプルリクエストブランチ名を表します
これは、GitHub Actionsが実行されるリポジトリのブランチやタグに基づいて、異なる処理を実行する必要がある場合に使用されます

トリガーごとのGITHUB_SHAとGITHUB_REF

GITHUB_SHAとGITHUB_REFはトリガーしたイベントごとに中身が変わります。各イベント(一部)のそれぞれの値をまとめたものになります

pull_requestではマージ時とそうでない時で値が変わるので注意

イベント	GITHUB_SHA	GITHUB_REF	GITHUB_REF 例
push	最新のコミットのSHA値	ブランチ名またはタグ名	refs/heads/main または refs/tags/v1.0.0
pull_request (opened,synchronize,close(クローズ))	PRの最後にpushされたコミットのSHA値	PRが作成されたブランチ	refs/heads/feature-branch
pull_request (close(マージ))	PRのマージコミットのSHA値	PRのマージ先ブランチ名	refs/heads/main
release	リリースを作成したコミットのSHA値	タグ名	refs/tags/v1.0.0
schedule	スケジュールされたジョブを実行するときのSHA値	ブランチ名またはタグ名	refs/heads/main または refs/tags/v1.0.0
workflow_dispatch	手動でトリガーされたジョブを実行するときのSHA値	ブランチ名またはタグ名	refs/heads/main または refs/tags/v1.0.0

pull_requestの環境変数

pull_requestイベントでは、比較先(base)ブランチと作業(head)ブランチを判別できる環境変数を使用する事ができます

以下がそれぞれの概要になります
(mainブランチに対してfeatureブランチを作成している場合)

環境変数	概要	値
GITHUB_BASE_REF	比較先のブランチ	refs/heads/main
GITHUB_HEAD_REF	作業ブランチ	refs/heads/feature-branch

まとめ

Github Actionsでは様々なイベントをトリガーでき、その中で様々な環境変数を使用する事ができます。

使用する値の中身を確認する作業が結構大変で、マージかそうで無いかでも違ったりして場合分けが複雑なので使用する時は場合分けと使用する値を整理していきたいと思います。