[Github Actions] 追加されたIssueを自動で Github Projects に紐付ける

はじめに

現在参画している新サービス開発では、Github Projects を使って変更管理・不具合管理をしており、管理票を Issue として作成する運用にしています。

その中で
「特定のリポジトリに追加された Issue は、自動で所定の Githubプロジェクトに紐付けてほしい（紐付け忘れるので）」
という要望があり、Github が公式に提供している action を利用してサクッと実現しました。

メモがてらその方法をシェアします。

利用する action

Issue・Pull Request（以下、PR） のイベントをトリガーに、それらをGithubプロジェクトに紐づける方法として、Github は以下の action を提供しています。
actions/add-to-project | Github

この action の概要は以下の通り。

• Issue・PRのイベントをトリガーに、Personal access token を利用して得た権限で、指定された Githubプロジェクト に紐づける
• サポートしている Issue・PR イベントは以下の通り
  • Issue
    • opened
    • reopened
    • transferred
    • labeled
  • Pull Request
    • opened
    • reopened
    • labeled
• その Issue・PR を処理対象とするかどうかの条件として、label での条件を設定することができる
  • 複数のラベルを指定可能。合致条件として AND と OR を指定できる

※ secret.GITHUB_TOKEN ではダメなのだろうかと思ったが、以下の stack overflow で回答されている通り、権限が不足するためNGでした。

それでは、具体的にどう導入するかを以下にご紹介します。

導入手順

Step 1. Personal access token（PAT） を作成する

以下のリンクからPATを作成することができる。
https://github.com/settings/tokens/new

その際、repo と project の権限が必要となるためチェックをつけておく。

Step 2. PAT を Repository secrett に登録する

PATを Github Actions から利用できるように、リポジトリの [Settings]->[Secrets and variables] -> [Actions] から Repository secrets に登録する。

より具体的な手順は、以下の Github ドキュメントを参照。
https://docs.github.com/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository

なお登録する際、 Name を ADD_TO_PROJECT_PAT にしておくと、add-to-project の README.md にあるサンプルがそのまま利用できる。

Step 3. Github Actions のワークフローyamlをリポジトリに追加

対象とするリポジトリの .github/workflows に、以下内容を書き換えてyamlファイルとして配置しコミット・プッシュする。

name: Add bugs to bugs project

on:
  issues: # ここを pull_request にすると、PRを対象にできる
    types:
      - opened # 前述のイベントを指定する

jobs:
  add-to-project:
    name: Add issue to project
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@RELEASE_VERSION #利用する Release バージョンに書き換える
        with:
          project-url: https://github.com/orgs/<orgName>/projects/<projectNumber> # 紐づけたいプロジェクトのURLをここに反映する
          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }} # Step 2 でシークレットの Name を ADD_TO_PROJECT_PAT にしていたら、そのままでOK
          labeled: bug, needs-triage # label条件を追加する場合、登録する
          label-operator: OR # ANDも指定可能

まとめ

上記の手順で、特定のリポジトリに作成された Issue を、自動で所定のGithubプロジェクトに紐づけることができます。

加えて、Github Projects の Workflows で Item added to project を有効化すれば、初期パイプラインも指定できるのでこちらも設定をオススメします。