GitHubリポジトリの更新をBacklogへ通知する

こんにちは。デバイスソフトウエア開発部の本間です。
最近の開発業務にて、課題や進捗は Backlog で管理し、ソースコードは GitHub で管理するプロジェクトがありました。

Backlog には、Backlog 内リポジトリへのコミットやプルリクエストを課題に紐づける機能があり、課題から関連するソースコードの変更履歴を簡単に追跡できます。しかし、リポジトリを外部の GitHub に置いた場合は、その機能は利用できません。GitHub 側へプッシュやプルリクエストした時、その都度 Backlog の課題へ手動でコメントするのは中々面倒です。

そこで今回は、GitHub 上で操作（プッシュやプルリクエスト）した時、関連する Backlog 課題に自動で通知する方法をご紹介します。

GitHub Actions

GitHub Actions を利用することで、コミットコメントやプルリクエストの内容から Backlog の課題キーを抽出し、Backlog API を通じて該当の課題に自動でコメント通知することができます。自力でスクリプトを書いて実現することもできますが、既に便利な Action が公開されているためそちらを利用してみます。

この backlog-notify は Action として GitHub Marketplace に公開されており、簡単に Workflow へ組み込むことができます。

backlog-notify を設定する

README の設定方法の通りに設定していきます。

Backlog API キーの取得

GitHub リポジトリから Backlog プロジェクトへ通知するための API キーを作成します。Backlog 課題への通知コメントは API キーを登録したアカウントが投稿することになる為、必要に応じて backlog-notify 用の BOT アカウントを作成しプロジェクトへ追加してください。

API キー登録したいアカウントでログインし、アカウントのメニューから 個人設定 → API → 登録 を押下し、キーを作成します。画像のぼかした部分が生成されたキーとなります。

API キーを GitHub に登録

GitHub リポジトリに先ほど作成した API キーを登録し、Workflow から参照できるようにします。

Backlog へ通知したいリポジトリのページを開き、下記の通り Settings → Secrets and variables → Actions → New repository secret を押下します。

Name は BACKLOG_API_KEY とし、Secret には作成した API キーを入力します。

collaborator による workflow の実行を制限

外部からのプルリクエスト時に、承認がなければ Workflow を実行できないようにします（Private リポジトリであれば本操作は不要です）

GitHub でリポジトリのページを開き、下記の通り Settings → Actions → General を押下し、画像内のチェックボックスにチェックを入れて Save します。

Workflow の作成

Backlog と連携したいリポジトリ内に、backlog-notify を実行する Workflow を作成します。

リポジトリ内に .github/workflows/backlog-notify.yml（ファイル名は任意）を作成し、下記内容を記述します。★ 箇所は、通知先の Backlog ドメインやプロジェクトキーなど、環境にあわせて適宜変更してください。

name: Backlog Notify

on:
  push:
  pull_request:
    types:
      - opened
      - reopened
      - ready_for_review
      - closed

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Backlog Notify
        uses: bicstone/backlog-notify@v5
        with:
          project_key: PROJECT_KEY ★
          api_host: example.backlog.jp ★
          api_key: ${{ secrets.BACKLOG_API_KEY }}

name: Backlog Notify

on:

push:

pull_request:

types:

- opened

- reopened

- ready_for_review

- closed

jobs:

notify:

runs-on: ubuntu-latest

steps:

- name: Backlog Notify

uses: bicstone/backlog-notify@v5

with:

project_key: PROJECT_KEY ★

api_host: example.backlog.jp ★

api_key: ${{ secrets.BACKLOG_API_KEY }}

プッシュしてみる

GitHub リポジトリへコミットをプッシュして、Backlog 課題へコメント通知されるか確認してみます。

なお、コミットのコメントには関連付けたい Backlog 課題キーを含める必要があります。Backlog 本家の追跡機能と違う点は、コメント１行目の先頭に課題キーを書く必要がある点です。書ける課題キーは１つだけで、複数の課題へ通知することはできません。また他には、１行目の末尾に #fixed や #closedを付けることで、プッシュした時に課題を「処理済み」や「完了」のステータスに変更することができます。複数の課題に通知できないのは残念ですが、課題のステータスをコミットで変更できるのは便利かもしれません。

それでは GitHub リポジトリへコミットをプッシュしてみます。

プッシュした後、下記の通り、Backlog 課題の TEST_PROJECT-12 に自動でコメントされることが確認できました。

Backlog 本家の機能とは違い、複数のコミットを同時にプッシュした場合は、１つのコメントにまとめて通知されるようです。コメント内の各リンクからはそのコミットの内容が確認できます。また、最後のコミットには #fixed を付けている為、課題のステータスが「処理済み」に変更されています。

プルリクエストしてみる

GitHub のリポジトリ内でプルリクエストを作成・マージして、Backlog 課題へコメント通知されるか確認してみます。

Backlog 課題と関連付ける場合は、コミットコメントと同じように、プルリクエストの題名の先頭には課題キーを書く必要があります。書ける課題キーは１つだけで、複数の課題へ通知することはできません。

それでは GitHub でプルリクエストを作成してみます。

プルリクエストした後、下記の通り、Backlog の TEST_PROJECT-12 の課題に自動でコメントされることが確認できました。コメント内のリンクからは該当のプルリクエストを見ることができます。

続けて、プルリクエストをマージしてみます。Merge pull request を押下してマージを実行しました。

マージした後も、下記の通り、TEST_PROJECT-12 の課題に自動でコメントされることが確認できました。main へマージコミットした旨と、プルリクエストをマージした旨がコメントされています。

コメントのテンプレートを変える

Backlog では、プロジェクト毎に文章記述で使用するマークアップ言語の記法を設定できます。選べる記法は「Backlog記法」「Markdown記法」の２つです。この２つの記法は似ていますが、見出しやリンク、箇条書きなどの書き方が微妙に異なります。

backlog-notify は、デフォルトで Markdown 記法でコメントを投稿します。その為、もし Backlog プロジェクト側が Backlog 記法で運用している場合、下記の通りコメント内のリンクや箇条書きが意図しない表示となってしまいます。

この問題は、backlog-notify の設定を変更し、Backlog 記法でコメントを投稿するように指定することで解消できます。下記の通り Workflow の下部にコメントテンプレートを追記することで、Backlog 記法へ変更することが可能です。

name: Backlog Notify

on:
  push:
  pull_request:
    types:
      - opened
      - reopened
      - ready_for_review
      - closed

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Backlog Notify
        uses: bicstone/backlog-notify@v5
        with:
          project_key: PROJECT_KEY
          api_host: example.backlog.jp
          api_key: ${{ secrets.BACKLOG_API_KEY }}
          push_comment_template: |-
            <%= commits[0].author.name %>さんが[[<%= ref.name %>:<%= ref.url %>]]にプッシュしました
            <% commits.forEach(commit=>{ %>
            - [[<%= commit.comment %>:<%= commit.url %>]] (<% print(commit.id.slice(0, 7)) %>)<% }); %>
          pr_opened_comment_template: |-
            <%= sender.login %>さんがプルリクエストを作成しました

            - [[<%= title %>:<%= pr.html_url %>]] (#<%= pr.number %>)
          pr_reopened_comment_template: |-
            <%= sender.login %>さんがプルリクエストを作成しました

            - [[<%= title %>:<%= pr.html_url %>]] (#<%= pr.number %>)
          pr_ready_for_review_comment_template: |-
            <%= sender.login %>さんがプルリクエストを作成しました

            - [[<%= title %>:<%= pr.html_url %>]] (#<%= pr.number %>)
          pr_closed_comment_template: |-
            <%= sender.login %>さんがプルリクエストをクローズしました

            - [[<%= title %>:<%= pr.html_url %>]] (#<%= pr.number %>)
          pr_merged_comment_template: |-
            <%= sender.login %>さんがプルリクエストをマージしました

            - [[<%= title %>:<%= pr.html_url %>]] (#<%= pr.number %>)

name: Backlog Notify

on:

push:

pull_request:

types:

- opened

- reopened

- ready_for_review

- closed

jobs:

notify:

runs-on: ubuntu-latest

steps:

- name: Backlog Notify

uses: bicstone/backlog-notify@v5

with:

project_key: PROJECT_KEY

api_host: example.backlog.jp

api_key: ${{ secrets.BACKLOG_API_KEY }}

push_comment_template: |-

<%= commits[0].author.name %>さんが[[<%= ref.name %>:<%= ref.url %>]]にプッシュしました

<% commits.forEach(commit=>{ %>

- [[<%= commit.comment %>:<%= commit.url %>]] (<% print(commit.id.slice(0, 7)) %>)<% }); %>

pr_opened_comment_template: |-

<%= sender.login %>さんがプルリクエストを作成しました