はじめに
GitHub Actions Required workflows が2023/1/10 に public betaになりました。
そして、2023/8/2 に Repository Rules に統合され今に至ります。
Public Betaとしての提供を終え、現在ではGitHub Enterpriseでのみ利用可能な機能となっています。
Required workflows は Organization 配下のリポジトリにワークフローの実行を強制させる機能です。
今回は Required workflows 利用方法をハマりポイントを交えながらご紹介していきます。
Required Workflows の利用
まずは、Required workflows として実行させる workflow ファイルを配置するためのリポジトリを作成する必要があります。
ハマりポイント リポジトリの可視性
このときリポジトリの可視性に注意する必要があります。
プライベート リポジトリに格納されているワークフローは、Organization 内の他のプライベート リポジトリの必要なワークフローとして構成できます。 内部リポジトリに格納されているワークフローは、Organization 内の内部リポジトリとプライベート リポジトリの必要なワークフローとして構成できます。
と、ドキュメントにあるようにPublic / Internal / Private 全ての可視性で実行させるためには Public リポジトリに workflow を配置する必要があります。
プライベートリポジトリに存在する workflow を パブリックリポジトリで実行すると Worfklows cannnot be required from a less visible repository というエラーが発生します。
またリポジトリの設定で Organization 配下のリポジトリからのアクセス許可を設定する必要があります。
Accessible from repositories in the hoge organization を選択してください。
Required workflows は Organization配下のリポジトリにのみ実行可能であり、Organization 跨ぎは不可能なため Accessible from repositories in the hoge enterprise の権限は過剰です。
ハマりポイント workflow の格納場所
wokflowの格納場所は .gihtub/workflows です。
必要なワークフローは、任意のリポジトリ フォルダーに格納可能で、通常のワークフローのように .github/workflows フォルダーに限定されることはありません。
と、ドキュメントにはありますが、実際には .gihtub/workflows に限定されており、これ以外の格納場所だと後の Required workflows の設定で workflow を指定することができません。
こちらは GitHub Community で言及されています。
This is a deliberate choice, and we don't intend to support workflows outside of the .github/workflows directory, right now an if condition is the best way of handling things I think. We may revisit this if it turns out to be a major pain point, so we are listening to this feedback 👍
https://github.com/orgs/community/discussions/67754#discussioncomment-7201502
今回は .github/workflows/example.yaml という簡素なものを作成しました。
トリガーとして指定できるのは pull_request / pull_request_target / merge_group イベントのみです。
name: Hello World
on: pull_request
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Hello World
run: echo "Hello World!"
次に Organization の設定を変更して .github/workflows/example.yaml を他のリポジトリで実行してみます。
Organization の設定画面から 左サイドバー「Code, planning, and automation」の Repository > Rulesets から設定していきます。
Enforcement status
Disabled / Evaluate / Active の 3つから選択可能です。
Evaluate mode は 「実行はされるが、Branch protections で指定した規則は適用しない」という動作になります。
また、実行結果は Repository > Ruleset insights から一覧で表示することが可能となります。
Target repositories
All Repository / Dynamic list by name / Dynamic list by property / Select repositories から選択可能です。
今回は、Select repositories で指定したリポジトリだけで実行させるようにしています。
Dynamic list by property は Custom Properties という執筆段階では Beta 版の機能を用いて対象とするリポジトリを選択するものです。
本筋と離れてしまう為今回は省略します。こちらにドキュメントがあります。
Branch protections
Required workflows の 設定はここで行います。
Require workflows to pass before merging に チェックを入れて実行したい workflow の PATHを入力します。
.github/workflows 配下のファイルがサジェストされます。PATHを直接入力することもできますが、前述した通り実行できるのは .github/workflows 配下の workflow のみです。
Pull Request を 作成してみると、設定した Required workflows が無事実行されました。
さいごに
Required workflows は Organization 配下のリポジトリにワークフローの実行を強制させることができ、統制をとるには非常に便利な機能です。
GitHub Enterprise plan でしか利用できず、個人で試すのには金銭的なハードルが高いですが、Enterprise plan を契約している組織であれば簡単に試すことができます。
Evaluate mode で 影響範囲を事前に確認しつつ、段階的に統制をとることができるのも魅力的です。
Linter の 実行等を強制させたい場合に利用することを検討にいれてもいいかもしれません。
ジャストアイデアではありますが、CODEOWNERS が配置されているかを検査しリポジトリ保護に役立てるのもいいかもしれません。
GitHub Community で 偶然見かけたのは Yelp detect-secrets を使い、秘匿情報が含まれているかどうかのスキャンを行なっている方もいました。
GitHub Enterprise を導入していることが必須かつ、Organization 全体に影響してしまうというハードルはあるものの、任意の workflow の実行を強制できるためより柔軟なルールを適用することができそうです。