LoginSignup
2
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@bicstone

Backlog の課題に GitHub のプルリクを連携する GitHub Action を作りました

Last updated at Posted at 2024-09-19

プルリクストをBacklog課題のコメントに追加するGitHub Actionを公開しました。ぜひご利用ください。

※ これは2022-12-01に個人ブログで公開した記事を移植し、MITで提供しています。情報は古い可能性があります。

GitHub Action

GitHub Actionとは、GitHub内で完結するCI / CDツールです。個人開発や仕事で大変お世話になっています。

そのうち、仕事で活用できたパッケージを1つ公開し、GitHub Marketplaceに公開しています。

Backlog Notify

プッシュされたりプルリクストが作成されたらBacklog課題のコメントにリンクコメントを送信するGitHub Actionです。キーワードによる課題の状態変更も可能です。

使用方法

プルリクエスト

Backlog Notifyの動作をイメージした図。GitHub にプルリクエストを作成すると Backlog にプルリクエスト情報のコメントがされる

プルリクエストのタイトルの中に課題番号 (例: PROJECT-123 ) がある場合は、その課題にプルリクエストに関するコメントを送信します。課題キーは先頭にある1つのみ認識します。

PROJECT-123 不具合修正

また、キーワードがある場合は、マージされたタイミングで課題ステータスを変更します。キーワードは末尾にある1つのみ認識します。

  • #fix #fixes #fixed のどれかで処理済み
  • #close #closes #closed のどれかで完了
PROJECT-123 不具合修正 #fix

プッシュ

Backlog Notifyの動作をイメージした図。GitHub にプッシュすると Backlog にコミット情報のコメントがされる

コミットメッセージの中に課題番号 (例: PROJECT-123 ) がある場合は、その課題にコミットログに関するコメントを送信します。課題キーは先頭にある1つのみ認識します。

PROJECT-123 不具合修正

また、キーワードがある場合は、プッシュされたタイミングで課題ステータスを変更します。キーワードは末尾にある1つのみ認識します。

  • #fix #fixes #fixed のどれかで処理済み
  • #close #closes #closed のどれかで完了

ちなみに空コミットすることで、Backlogを開かずともコメントを残したりステータスを変更できます。

PROJECT-123 不具合修正 #fix

設定方法

BOT ユーザーの作成

  1. Backlogのプロジェクトに移動します。
  2. プロジェクト設定 → 参加ユーザー → 新しいユーザの追加はこちらからを選択します。
  3. クラシックプランの場合は 一般ユーザ 、新プランの場合は ゲスト を選択します。
  4. 登録します。

Backlog.com のスクリーンショット 「プロジェクト設定」→「参加ユーザー」→「新しいユーザーの追加はこちら」を選択する

Backlog API キーの取得

  1. 登録したBOTアカウントにログインします。
  2. 個人設定 → API → 登録でAPIキーを発行します。

Backlog.com のスクリーンショット 「ユーザー設定」→「API設定」からAPIを発行します

API キーを GitHub に登録

  1. GitHubのリポジトリページに移動します。
  2. Setting → Secrets → Add a new secretを選択します。
  3. Nameは BACKLOG_API_KEY とし、 ValueにAPIキーをそのまま貼り付けます。
  4. 登録します。

GitHubのプロジェクトスクリーンショット　リポジトリの「Settings」→「Secrets」→「Add a new secret」 を選択して、 BACKLOG_API_KEY を追加する

collaborator による workflow の実行を制限

プライベートリポジトリの場合は次の操作する必要はありません。
パブリックリポジトリの場合は、collaboratorからのworkflowの実行を制限してください。

  1. Setting → Actions → Fork pull request workflows from outside collaboratorsを開きます。
  2. Require approval for all outside collaborators を選択します。

GitHubのプロジェクトスクリーンショット　リポジトリの「Settings」→「Actions」→「Fork pull request workflows from outside collaborators」

Workflow の作成

GitHub Actions workflowを作成します (例: .github/workflows/backlog-notify.yml )。

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@v4
        with:
          project_key: PROJECT_KEY
          api_host: example.backlog.jp
          api_key: ${{ secrets.BACKLOG_API_KEY }}

高度な設定

Workflow syntax for GitHub Actions - GitHub Docs を参照に実行する条件を制御できます。
また、コメントのフォーマットや、メッセージを解析する際の正規表現などをカスタマイズできます。

name: Backlog Notify
on:
  push:
    branches:
      - main
  pull_request:
    types:
      - opened
      - reopened
      - ready_for_review
      - closed
    branches:
      - releases/**
jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Backlog Notify
        uses: bicstone/backlog-notify@v4
        with:
          # 必須設定 (The following are required settings)
          project_key: PROJECT_KEY
          api_host: example.backlog.jp
          api_key: ${{ secrets.BACKLOG_API_KEY }}
          # 任意設定 (The following are optional settings)
          fix_keywords: |-
            #fix
            #fixes
            #fixed
          close_keywords: |-
            #close
            #closes
            #closed
          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 %>)
          commit_message_reg_template: "\
            ^\
            (<%= projectKey %>\\-\\d+)\\s?\
            (.*?)?\\s?\
            (<% print(fixKeywords.join('|')) %>|<% print(closeKeywords.join('|')) %>)?\
            $\
            "
          pr_title_reg_template: "\
            ^\
            (<%= projectKey %>\\-\\d+)\\s?\
            (.*?)?\\s?\
            (<% print(fixKeywords.join('|')) %>|<% print(closeKeywords.join('|')) %>)?\
            $\
            "
          fix_status_id: 3
          close_status_id: 4

設定一覧

設定名 説明
project_key Backlog プロジェクトキー (必須)
api_host Backlog のホスト (必須)
api_key Backlog API キー (必須)
fix_keywords 処理済みにするキーワード
close_keywords 完了にするキーワード
push_comment_template プッシュ時のコメント雛形
pr_opened_comment_template プルリクエストオープン時のコメント雛形
pr_reopened_comment_template プルリクエスト再オープン時のコメント雛形
pr_ready_for_review_comment_template プルリクエスト下書き解除時のコメント雛形
pr_closed_comment_template プルリクエストクローズ時のコメント雛形
pr_merged_comment_template プルリクエストマージ時のコメント雛形
commit_message_reg_template コミットメッセージ解析の正規表現雛形
pr_title_reg_template プルリクエストタイトル解析の正規表現雛形
fix_status_id 処理済みの 状態 ID
close_status_id 完了の 状態 ID

push_comment_template

プッシュ時のコメントの雛形を変更できます。
構文については lodash/template をご参照ください。

使用可能な変数
変数名 型
commits ParsedCommit[]
ref ParsedRef

ParsedCommit

変数名 型
id string
tree_id string
distinct boolean
message string
timestamp string
url string
author Committer
committer Committer
added string[]
modified string[]
removed string[]
issueKey string
comment string
keywords string
isFix boolean
isClose boolean

ParsedRef

変数名 型
name string
url string

Committer

変数名 型
name string
email string | null
date string | undefined
username string | undefined

pr_*_comment_template

プルリクエストイベントのコメントの雛形を変更できます。
構文については lodash/template をご参照ください。

使用可能な変数
変数名 型
pr PullRequest
action "opened" | "reopened" | "ready_for_review" | "closed" ※1
sender User
issueKey string
title string ※2
keywords string
isFix boolean
isClose boolean

※1: マージとクローズは共に "closed" となります。マージであるかを判別したい場合は pr.merged を参照ください。
※2: 課題キーとキーワードを除いたタイトルです。加工前のタイトルは pr.title を参照ください。

PullRequest

Get a pull request - GitHub Docs のResponse schemaをご参照ください。

User

Get the authenticated user - GitHub Docs のResponse schemaをご参照ください。

commit_message_reg_template

コミットメッセージ解析の正規表現雛形を変更できます。
構文については lodash/template をご参照ください。

{/lint ignore no-duplicate-headings/}

使用可能な変数
変数名 型
projectKey string
fixKeywords string[]
closeKeywords string[]

pr_title_reg_template

プルリクエストタイトル解析の正規表現雛形を変更できます。
構文については lodash/template をご参照ください。

使用可能な変数
変数名 型
projectKey string
fixKeywords string[]
closeKeywords string[]

よくある質問と回答

  • 何をプッシュしても実行に失敗し、ログに401エラーとある
    APIキーが誤っている可能性があります。

  • プロジェクトキーと課題キーが正しいのにも関わらず、実行に失敗し、ログに404エラーとある
    該当APIキーのユーザーがプロジェクトに参加していない可能性があります。

料金について

GitHub Actionsは処理時間で課金されるためできるだけ実行時間を減らすよう設計しています。

ncc を活用し、単一のファイルにコンパイルしたNode.jsのプログラムとなっており、数秒で実行が完了します。2コミットでは3秒でした。とてもエコです。

GitHub Actions の実行履歴スクリーンショット

まとめ

もし、便利だと思ったらスター頂ければ幸いです。実はしばらくBacklogを使用しておらず、多くの方に使用していただいているという責任感で維持している状態です。反響があると、維持するモチベーションに繋がります。

よろしくお願いいたします。

2
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?