Scala StewardとGitHub Actionsで依存ライブラリの更新を自動化する
[AD] scalapediaでは記事作成ボランティアを募集しています
この記事では、Scalaアプリケーションが依存するライブラリのアップデート作業をScala StewardとGitHub Actionsを使って自動化する方法について解説します。
サンプルコードは以下のリンク先に置いてあります。合わせてご確認ください。
Scala Steward は依存ライブラリの更新を確認するツール
Scala Stewardは、依存ライブラリの更新を確認するツールです。
Scala Stewardを実行すると、GitHubにホストされているScalaプロジェクトの、依存ライブラリやsbt本体、sbtプラグインについて更新を確認し、更新があればPull Requestが作成されます。
Pull Requestにはリリースノートへのリンクも含まれているので、レビュー・マージも簡単です。
かつて手動で更新の有無を確認して、その更新の内容を確認して、問題なさそうであればbuild.sbtを変更してPull Requestを作成してテストを回して・・・といった非常に面倒な一連の流れの大部分をScala Stewardが担ってくれます。
これによって人間は「更新の内容について問題があるかどうか確認してマージする」だけで良くなりました。
革命的ですね。ぜひ活用しましょう。
プライベートリポジトリで実行するには工夫が必要
Scala Stewardには、公式が運営するインスタンスが存在しています。
GitHubにホストされているパブリックリポジトリに対しては、この公式インスタンスに登録すれば監視対象に含めて自動的にPull Requestを作成してくれます。
プライベートリポジトリに対しては公式のインスタンスをアクセスさせるわけにはいかないため、別のインスタンスを用意して実行する必要があります。
実行するには例えばCircleCIやGitHub Actions使う方法がありますが、この記事ではGitHub Actionsを使用して定期実行する方法を解説します。
GitHub Actions でScala Stewardを自動実行するには scala-steward-action を使う
GitHub Actionsは、GitHub上のコードに対する処理を自動化するための、GitHub公式の機能です。
普段GitHubを使用している場合は、GitHub ActionsでScala Stewardの実行を自動化したいですよね。
GitHub Actions でScala Stewardを定期実行するには、 scala-steward-action を使います。
GitHub ActionsでScala Stewardを実行するパターン
GitHub ActionsでScala Stewardを実行する場合、2つの観点から検討して最適なパターンを選択する必要があります。
- 誰のアカウントで実行したいか？
- 自分
- アクセス権限の設定は必要ありません
- Scala Stewardが自分のアカウントの名義でコミットやPull Requestをします
- botアカウント（machine user）
- botアカウントにアクセス権限を与える必要があります
- Scala Stewardがbotアカウントの名義でコミットやPull Requestをします
- 自分
- いくつのリポジトリを扱いたいか？
- 1つだけ
- 対象のリポジトリのGitHub ActionsでScala Stewardsのジョブを実行します
- 複数
- ジョブ管理用のリポジトリを作成し、その管理用リポジトリのGitHub ActionsでScala Stewardsのジョブを実行します
- 1つだけ
以下、それぞれの観点について説明します。
アクセス権について検討する
Scala StewardをGitHub Actionsで実行する場合、誰のアカウントで、どのリポジトリに対して実行するか検討する必要があります。
というのも、Scala Stewardに対してコミットやPull Requestなどの操作を行う権限を与える必要があり、つまりコミットやPull Requestはその権限を与えたアカウントの名義で行われることになるからです。
自分のアカウントで実行しても差し支えなければ、特別な対応は不要です。
チームで管理しているリポジトリなど、botの活動を特定の個人に結びつけたくない場合などには、自動化のためのサブアカウント（machine user）を作成する必要があります。
"machine user"は、無料ユーザー一人につき一つだけ保有できることがGitHubの利用規約において定められています。
この記事では、チームで管理することを想定し、botアカウント（machine user）にアクセス権限を与えてScala Stewardを自動実行する方法を紹介します。
botアカウントを作成しない場合は、適宜読み替えてください。
リポジトリの個数について検討する
自動で更新したいリポジトリが幾つあるのかについても検討する必要があります。
自動で更新したいリポジトリが1つだけである場合、そのリポジトリのGitHub ActionsにScala Stewardのジョブを設定することで自動実行させることができます。
これに対して、管理対象のリポジトリが複数ある場合や、今は1つでも今後増える可能性がある場合には、ジョブ管理用のリポジトリを別途作成し、この管理用リポジトリのGitHub ActionsにScala Stewardを設定して自動実行することになります。
ただし、既存のリポジトリ上で複数のリポジトリを管理することもできます。
例えば、中心的なリポジトリが存在していて、そこで管理したいという場合が考えられます。 この場合には管理用リポジトリを別途用意する必要はありません。
この記事では、複数のリポジトリを管理したい場合を想定し、ジョブ管理用リポジトリを作成してScala Stewardを自動実行する方法を紹介します。
ジョブ管理用リポジトリを作成しない場合は、適宜読み替えてください。
ジョブ管理用リポジトリを作る
まずは、Scala Stewardのジョブや、監視対象とするリポジトリを管理するためのリポジトリを作成しましょう。
Organizationがあれば、そこに管理用リポジトリを作りましょう。
逆に、後ほど作成するbotサブアカウントにリポジトリを作らせてしまうと、このリポジトリを管理する際に毎回サブアカウントにログインする必要がでてきます。
面倒ですのでおすすめしません。
監視対象リポジトリ一覧ファイルを作成する
ジョブ管理用リポジトリに、監視対象リポジトリの一覧ファイルを作成します。
この作業はWeb上で行うことができます。
/repos.md に対して、以下のような内容を記述して保存します。
markdown# repos.md - organization/repository
管理対象としたいリポジトリを、この箇条書きに一つ一つ列挙してください。
ファイルを作成したコミットは必ずデフォルトブランチに取り込んでおきましょう。
ジョブファイルを作成する
ジョブ管理用リポジトリに、ジョブ定義ファイルを作成します。
この作業もWeb上で行うことができます。
/.github/workflows/scala-steward.yml に、以下のような内容のファイルを作成します。
yamlon: schedule: - cron: '0 0 * * *' workflow_dispatch: jobs: scala-steward: runs-on: ubuntu-latest name: Launch Scala Steward steps: - name: Checkout uses: actions/checkout@v2 - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-token: ${{ secrets.ADMIN_GITHUB_TOKEN }} author-email: bot-account@example.com repos-file: 'repos.md'
注目すべき点は、github-token と author-email と repos-file です。
github-tokenは、後ほど作成するbotアカウントのPersonal Access Tokenです。
author-email は、後ほど作成するbotアカウントのメールアドレスです。
author-emailの指定を省略したい場合、サブアカウントのプロフィールにてメールアドレスを公開する必要があります。- サブアカウントのメールアドレスを一般公開する意味はないでしょうから、ここではメールアドレスを明示的に指定しておきます。
repos-fileには、先ほど作成した一覧ファイルを指定します。
また、以下の点にも留意しておきましょう。
scheduleでは、cron形式で実行間隔を指定できます。
cron形式については以下の記事が詳しいです。
workflow_dispatchを指定すると、任意のタイミングでジョブを実行できるようになります。
デバッグしやすくなりますので、ぜひ付けておきましょう。
ステップは、scala-steward-org/scala-steward-actionのほかに、actions/checkoutも必要になります。
repos.mdを参照するのにリポジトリをチェックアウトする必要があります。
これで、このファイルを元にScala Stewardが自動実行されるようになりました（※もちろんまだ成功しません）。
botアカウント（machine user）を作成する
次に、botアカウント（machine user）を作りましょう。
GitHubのアカウントを作成する手順は以下のページにて詳しく解説しています。
Personal Access Tokenを作成する
bot用のGitHubアカウントを作成したら、botアカウントのPersonal Access Tokenを作成しましょう。
このPersonal Access Tokenを使用することで、Scala Stewardによって作成されるコミットやPull Requestがbotアカウント名義になります。
開発者設定（Developer Settings）のPersonal Access Token一覧画面を開き、右上の"Generate new token"をクリックします。
Personal Access Tokenの新規作成画面では、識別しやすい名前をつけ、「repo」の権限を付与した上で、左下の"Generate token"をクリックします。
これで、Personal Access Tokenが作成できました。
このトークンは後で使うので、一旦どこかにメモしておきましょう。
Personal Access Tokenの詳しい作り方については、以下の記事にて解説しています。
管理用リポジトリと監視対象の各リポジトリにbotアカウントを招待する
botアカウントは管理用リポジトリと監視対象のリポジトリの全てにアクセスできる必要があります。
それぞれのリポジトリからbotアカウントを招待し、botアカウントが各リポジトリにアクセスできるようにしてください。
リポジトリにbotアカウントを招待する手順は、以下の記事で詳しく解説しています。
管理用リポジトリの "Action secrets" にPersonal Access Tokenを登録する
"Action secrets"とは、GitHub Actionsにて参照される環境変数のことです。
Scala Stewardに対してbotアカウントのPersonal Access Tokenを渡すためにAction secretsを利用します。
ここではADMIN_GITHUB_TOKENというAction secretsを作成し、先程作成したbotアカウントのPersonal Access Tokenを登録します。
リポジトリの設定画面を開くと、左サイドバーに"Secrets"というボタンがあります。
これをクリックすると、Action secretsの一覧画面に遷移します。
Action secrets一覧画面にて右上の"New repository secret"ボタンをクリックすると、Action secretsのの新規作成画面に遷移します。
NameにはADMIN_GITHUB_TOKEN、Valueには先程作成したbotアカウントのPersonal Access Tokenを入力し、"Add secret"をクリックします。
これで、Scala Stewardの実行に必要な環境は揃いました。
実行する
それでは、Scala Stewardを実行してみましょう。
scala-steward.yml にて workflow_dispatch を有効化しているので、任意のタイミングでジョブを実行することができます。
管理用リポジトリのページにおいて、リポジトリ名の下のメニューバーにある"Actions"タブをクリックします。
左サイドバーにはActionsの一覧が表示されています。
このなかに、先程作ったジョブが表示されているはずです。これをクリックします。
そうすると、"This workflow has a workflow_dispatch event trigger."と表示された青い網掛け部分が表示されます。
この右側の"Run workflow"ボタンをクリックし、さらに表示されるモーダルの"Run workflow"ボタンをクリックするとジョブが開始されます。
首尾よく終了したら、あとでcronの設定通りに動いているかも確認しておきましょう。
これで、Scala StewardとGitHub Actionsを使って依存ライブラリのアップデート作業を自動化することができます。