GitHub の Issue を自動で Project に追加する方法3選

この記事は、ニフティグループ Advent Calendar 2023 11日目の記事です。

基幹システムグループ N1! オートメーションスペシャリストの南川です。

現在、私が所属しているチームでは複数のプロダクトの開発をしており、プロダクトごとに GitHub リポジトリも分かれています。複数のリポジトリの Issue を一つの Project で管理するために、 Issue を Project に追加する作業を行う必要がありますが、それらを手動でやるとなると面倒だと思います。手動でやるとなると手間もかかりますし、Project への追加し忘れや追加先を間違えるといったミスも出てきます。この作業を自動化することで、手作業によるコストや作業ミスを減らし、ストレスの無い開発をすることができます。

今回は、GitHub の Issue を自動で Project に追加する方法として以下の3つを紹介します。

• (方法 A) 組み込みの自動化ワークフローを使う
• (方法 B) GitHub Actions + actions/add-to-project を使う
• (方法 C) GitHub Actions + GitHub CLI を使う

なお、こちらの記事は2023年11月に開催された技術書展15にて頒布したニフティの技術書「NIFTY Tech Book #1」で掲載された第8章の内容とほぼ同一のものとなります。無料で電子版を頒布しているので、他の記事も気になる方はダウンロードしてみてください。

また、明日に技術書の主催による技術書を出版するまでの記事も投稿されるので、そちらも要チェックです！

(方法 A) 組み込みの自動化ワークフローを使う

2023年1月 エンタープライズアカウント向けに、特定の条件を満たしたIssueをProjectに追加する組み込みワークフローがリリースされました。組み込みワークフローでは、ノーコードで以下のような一連の流れを自動化することができます。

• 項目 (Issue や Pull request) がプロジェクトに追加された場合、それらのステータスを Todo に設定する。
• 項目が Close された場合、それらのステータスを Done に設定する。
• 新規作成や更新された項目が特定の条件を満たしていた場合、それらを Project に追加する。

設定方法については公式のドキュメントが分かりやすいのでそちらをご参照ください。

メリットとデメリット

この方法のメリットは、コードを書かずに GUI 上で設定でき、手軽に導入できるという点です。組み込みワークフローは複製することができ、複数のリポジトリに対する導入も容易だと思います。

しかし、作成できる個数に上限が決まっているというデメリットもあります。このワークフローを作成できる上限はプランによって異なり、以下の表の通りです。

プラン	上限個数
GitHub Free	1
GitHub Pro	5
GitHub Team	5
GitHub Enterprise Cloud	20
GitHub Enterprise Server	20

Each workflow can target a different repository, allowing you to add items from up to four repositories.

https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically

また、最大4つのリポジトリまで項目を追加できるということで、それ以上のリポジトリを持っている私のチームではこの方法では厳しいと判断しました。

そのような場合に、これから紹介する2つ目、3つ目の方法が有用です。

GitHub Actionsを使う

GitHub Actions は GitHub まわりのワークフローを自動化するプラットフォームで、以下の用途などに使うことができます。

• Issue が作成されたら、 Project に追加する。
• Pull request が作成されたら、 lint 、テストを実行する。
  • 失敗した場合はマージをブロックする。
• Pull request がマージされたら、開発環境にデプロイする。
• コミットがプッシュされたら、 AWS CodeCommit とミラーリングする。

GitHub Actions で Issue を Project に追加する方法は以下の2通りになります。

• actions/add-to-project を使う。
• GitHub CLI (gh project item-add コマンド) を使う。

それぞれの方法についてこれから説明していきます。

(方法 B) GitHub Actions + actions/add-to-project を使う

actions/add-to-project は、 Issue や Pull request を Project に追加する Action です。 GitHub Actions と actions/add-to-project を使って、新たに作成した Issue を Project に自動追加させる手順を以下に示します。

(1) Personal Access Token の作成

公式のドキュメントを参考に、 Classic 版の Personal Access Token (PAT) を作成します。指定するスコープは以下の通りです。

• project
• repo (プライベートリポジトリの場合)

参考 : https://github.com/marketplace/actions/add-to-github-projects#creating-a-pat-and-adding-it-to-your-repository

(2) Repository Secret の追加

公式のドキュメントを参考に、 Repository Secret に手順 (1)で作成した PAT を追加します。
今回追加する Secret は以下の通りです。

• Name : ADD_TO_PROJECT_PAT
• Secret : < 手順 (1)で作成したPAT (ghp_…) >

(3) ワークフローファイルの作成

.github/workflows 配下に以下のファイルを作成します。

解説

• name では、リポジトリの Actions タブで表示されるワークフロー名を指定しています。
• ここで指定した名前は、 Actions タブの実行履歴で表示されます。

---

• on では、このワークフローを実行するトリガー (条件) を指定しています。
• issues は、ワークフローのリポジトリ内の Issue に対し、 types で指定したアクティビティが発生したときにイベントをトリガーするイベントです。
• 今回は opened というアクティビティを指定しており、 Issue が Open になる（作成される）時にトリガーが発動します。

---

• jobs では、トリガーが発動した際に実行するジョブを定義します。
• 今回は add-to-project というIDのジョブを定義し、名前 (name) とジョブを実行するマシン (runs-on) を指定しています。

---

• uses では、このステップで実行するアクションを指定し、そのアクションの入力パラメータは with で指定します。
• with で指定する入力パラメータは以下の通りです。
  • project-url (必須)
    • Issue を追加する GitHub Project の URL。
  • github-token (必須)
    • repo と project のスコープを持つ Personal Access Token(PAT) 。
  • labeled (オプション)
    • Project に追加する対象となる Issue をフィルタリングするためのラベル。
    • 複数指定する場合はカンマ区切りで指定します。
    • 指定しない場合は全ての Issue を Project に追加します。
  • label-operator (オプション)
    • ラベルフィルタの動作を指定します。
    • AND, OR, NOT のいずれかを指定します。デフォルトは OR です。

(方法 C) GitHub Actions + GitHub CLI を使う

GitHub CLI は、コマンドラインから GitHub を使用するためのオープンソースのツールです。 Issue の作成や一覧表示、 Pull request の差分表示やマージなどが出来ます。ドキュメントはこちらになります。

また、 GitHub Actions ではシェルを使用したコマンドラインプログラムも実行することができます。そして、 GitHub CLI はプリインストールされており、 GitHub Actions のワークフロー上で使うことができます。

GitHub Actions と GitHub CLI を使って、新たに作成した Issue を Project に自動追加させる手順を以下に示します。なお、手順(1)(2)は方法Bの手順(1)(2)と同様のため、省略します。

(3) ワークフローファイルの作成

.github/workflows 配下に以下のファイルを作成します。

解説

• run では、このステップで実行するコマンドを指定します。
  • GitHub CLI を使う各ステップでは、環境変数 GITHUB_TOKEN で必要なスコープを持つトークンを定義する必要があります。
  • 今回は、2023年7月に追加された gh project item-add コマンドを使って、 Project に Issue を追加します。

• env では、このステップで利用する環境変数を定義します。
• 「${{ github.event.issue.html_url }}」 でトリガーの発火元（作成した） Issue の URL を取得できます。
  • これは、コンテキスト (Context) と呼ばれ、これを使うことで、変数やランナーの環境、ステップの情報などにアクセスできるようになります。

メリットとデメリット

GitHub Actions を使う方法のメリットは、自由度が高いという点です。今回は Issue の Project への追加だけですが、 actions/slack-send を使って Slack チャンネルに Issue が作成されたことを通知するといったことも可能です。

しかし、ワークフローファイルを作成するのが手間であるというデメリットもあります。ただし、一度作ってしまえばコピペだけで済むのでそこまで気にならないでしょう。

方法B vs 方法C

actions/add-to-project と GitHub CLI のどちらを使えば良いかという話ですが、個人的にはどちらの方法でも良いかと思います。影響がありそうな違いでいうと、 actions/add-to-project は利用するバージョンを固定できますが、 GitHub CLI はプリインストールのためバージョンを固定するのは難しいかと思います。そのため、 GitHub CLI で今回使った gh project item-add コマンドについて破壊的変更があった場合、今回のコードに修正が必要になる可能性があり、その部分のメンテナンスコストを鑑みて決定することになるでしょう。

終わりに

今回は、作成した Issue を自動で GitHub Project に追加する方法を3つ紹介しました。紹介したそれぞれの方法についてですが、以下の判断基準で選ぶと良いと思います。

• 対象となるリポジトリが少なく、手軽に導入したい場合は、組み込みワークフローを使う方法A。
• 通知等の機能を追加するといった自由度を求める場合は、 GitHub Actions を使う方法B,C。
  • 方法BとCはお好みで選ぶ。
  • 方法Cはバージョン固定が難しいため、破壊的変更があった場合は対応が必要。

GitHub はアップデートで自動化などに役立つ便利な機能が追加されることがあるため、変更履歴を定期的に見てみるのもオススメです。

明日は、@iNakamura さんの「出版について何も知らない状態から技術書典に参加する技術」です。 お楽しみに！