Backlog Notify

Notify commit messages to Backlog.com issue.

GitHub 上のプッシュとプルリクエストを Backlog 課題に連携する GitHub Action です。キーワードによる課題の状態変更も可能です。

個人が開発した Action です。ヌーラボ様へのお問い合わせはご遠慮ください。

機能

プッシュ

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

PROJECT-123 不具合修正

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

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

PROJECT-123 不具合修正 #fix

※ 大量にプッシュするとそのまま投稿され、 Backlog に負荷がかかるのでご注意ください。

プルリクエスト

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

PROJECT-123 不具合修正

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

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

PROJECT-123 不具合修正 #fix

※ プルリクエストが Draft の状態である場合はコメント送信・ステータス操作をしません。
※ タイトルを変更した場合の通知は今のところ対応していません(対応予定)。Close → タイトルを変更 → Reopen を行うと通知されます。

設定方法

Backlog API キーの取得

Backlog のプロジェクトに移動します。
プロジェクト設定 → 参加ユーザー → 新しいユーザの追加はこちらからを選択します。
クラシックプランの場合は 一般ユーザ 、新プランの場合は ゲスト を選択します。
登録します。
登録した BOT アカウントにログインします。
個人設定 → API → 登録で API キーを発行します。

API キーを GitHub に登録

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

collaborator による workflow の実行を制限

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

Setting → Actions → Fork pull request workflows from outside collaborators を開きます。
Require approval for all 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@v5
        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@v5
        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