GitHub Actions: Reusing Workflows の管理

概要

私の管理している Reusing Workflow の考え方や管理方法の一部について紹介します

• Reusing Workflow の簡易説明
• Workflow の分割方針
• Workflow の構成
• Workflow の管理

について記載しています。

GitHub Enterprise版の機能も使っているので、それ以外のプランだと対応できない内容も含んでいます。

Reusing Workflow とは？

GitHub Actions の Workflow で共通の個所をまとめた他の Workflow から呼び出されることを目的とした Workflow です。

自作 Actions を作るほどの複雑さのものではないので、この方法を採用しています。

Workflow の分割方針

Reusing Workflow が一定の範囲の Workflow を切り出して共通の呼び出しを設けるものなので、Workflow をどう分割していくか、という話が出ます。

処理ごとの分割には「どこまでセットにするのか」という話はありますが、チーム内で比較的分かりやすい区切りがつくと思いますが、問題は(デプロイ)環境の違いをどの方法で対応するかだと思います。

環境ごとの Workflow をどう切り分けるかは諸方針あると思います。ざっと思いつくところだと

1. 環境ごとに別のファイルを作成する
2. ひとつの Workflow ファイル内で環境ごとの変数を入れ替える/固有の処理を作る

かなと。

どちらでも対応可能ですが、私は環境ごとに別のファイルを作成しています。理由としては現状の体制が元々 GitHub を使っていなかったメンバーもおり、比較的平易な対応で済ませたいというのがあります。

あまり試せていない(Reusing Workflow だと Environments との併用に課題があるため) ので一部推測ですが、変数の入れ替えは GitHub Environments

を使えば対応できるという認識です。

ただし、OIDC の token.actions.githubusercontent.com:sub が repo:<owner>/<repo>:environment:${environment-name} になるなど、他の個所への考慮事項がある認識です。

特定の環境でしか実施しない、バージョンの差/設定変更がある状態を一時的に保持したいというのもメリット・デメリットを出せるほどの比較検証はしていませんが、一旦フラットに書く方針としています。

Workflow の構成

以上の内容を踏まえて、 Reusing Workflow の構成は以下になっています。

呼び出し図

• プロジェクト用のレポジトリで環境ごとの workflow を作成して、その内部で Reusing Workflow を呼び出す
• Reusing Workflow 用のレポジトリの Reusing Workflow が変数を受け取って処理する共通的な処理(例:会社のメッセージサービスへの通知)
• 外部 Actions を呼び出して処理

という流れになします。

また、にReusing Workflow のレポジトリ側で Workflow の呼び出しの許可設定が必要です。

以前は Reusing Workflows は Enterprise 版にしかなかったレポジトリの可視権限の internal が必要だった記憶があるのですが、今は private で良いようでした。

許可設定に関しては以下公式ドキュメントを参考にしてください。

Workflow の管理(バージョン・告知他)

バージョン管理

バージョン管理はソフトウェアでもよくあるパターンだと思いますが

• メジャーバージョンタグ (例： v1 など)
  • 新規メジャーバージョンが作成されたときに作成
  • 同一メジャーバージョン内で新しいバージョンが出たら 新しいバージョンのタグが指すコミットに差し替え
• 固定バージョンタグ (例： v1.2.3 など)
  • 新しいリリースを作成するときに作成

の2つで実施しています。

初期の頃はマイナーバージョンの機能追加/修正もすることもあるのですが、最近はほぼメジャーとパッチバージョンのみの修正で、修正タイミングとしては

• メジャーバージョン変更
  • 呼び出している外部 Actions で破壊的な変更がある(≒ メジャーバージョンが変わった)とき
  • GitHub Actions の Runner の最低バージョンが変わったとき ※大抵の場合、上記で吸収されている
• マイナーバージョン変更
  • 機能追加
  • 引数追加 (オプションで、ディフォルト値はこれまでと挙動を変更しないようにする)
• パッチバージョン変更
  • メジャー/マイナーバージョンの変更に伴ってバグが発生した場合 ※外部アクションのバグ含む

となります。

この前提を元にプロジェクト側のレポジトリは以下のようにメジャーバージョンタグで Reusing Workflow を呼び出している用例が多いと思います。

jobs:
  reusable_workflow_job:
    uses: {owner}/{repo}/.github/workflows/reusable-workflow.yml@v1

バージョン更新の告知

GitHub 版 Dependabot でもバージョンアップのチェックはできる

※レポジトリの可視性に注意は必要ですが

ので、更新してくれているとは思いますが、特にメジャーバージョンアップのさいは告知するようにはしています。私が管理している Reusing Workflow では 2 つのチャンネルでの告知を行っています。

1. Reusing Workflow のリリース情報を投稿している社内メッセージングツールチャネルでの告知

リリースをトリガーにして社内のメッセージングツールにリリースノートを投稿する GitHub Actions Workflow があり、重要なリリースに関しては Bot の投稿に対して連絡事項を付与するようにしています。

ここはもう少し自動化の余地があるとは思っていますが、今のところそれ以上の対応はしていません。

※対応期限他、毎回個別に書いた方がよい内容もあったりするので

2. GitHub Workflow Commands を使った GitHub Actions のページへの表示

これは利用者の多くが

• メジャーバージョンタグで Reusing Workflow を参照している
• 何かしらの機会でレポジトリの Actions タブで Workflow の実行結果を見る

という前提に立ったオマケです。

確か GitHub 公式の Actions でこの用例を見てマネした記憶があります。

GitHub Workflow Commands を使うと、GitHub Actions の Workflow の実行結果ページにメッセージを表示することができます。

例えば v1 から v2 になるさいには以下の廃止メッセージを出力するジョブを v1 の最新版に追加しておきます。

echo "::warning file=reusable-workflow.yml, \
title=Deprecation Warning::v1 is going to deprecate \
because Node.js XX runtime will deprecate yyyy/mm/dd. \
Please update v2. see: https://github.com/{org}/{repo}/releases/tag/v2.0.0"

※表示の都合で改行していますが、実際は1行です

表示は以下のようになります。

末尾の URL を計測可能な短縮 URL などにしておけばどれくらい効果があったか測れるかもしれませんが、個人の趣味でやっている部分もあるのでよしとしています。

おわりに

私の管理している Reusing Workflow の考え方や管理方法の一部について紹介しました。

対応手順についてはドキュメントを書いているのですが、機能や考え方はドキュメントだけではなかなか伝わらないこともあり、管理の属人化が進んでいます。

来年はそのあたりにも対応できればなと思います。