Github ActionsにおけるGITHUB_SHAとGITHUB_REF #GitHub

はじめに

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では様々なイベントをトリガーでき、その中で様々な環境変数を使用する事ができます。

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

Github ActionsにおけるGITHUB_SHAとGITHUB_REF