https://github.com/bicstone/backlog-notify
GitHub 上のプッシュとプルリクエストを Backlog 課題に連携する GitHub Action です。
https://github.com/bicstone/backlog-notify
actions backlog github-actions hacktoberfest nulab nulab-backlog
Last synced: 10 months ago
JSON representation
GitHub 上のプッシュとプルリクエストを Backlog 課題に連携する GitHub Action です。
- Host: GitHub
- URL: https://github.com/bicstone/backlog-notify
- Owner: bicstone
- License: mit
- Created: 2019-11-15T14:02:13.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-04-28T19:25:41.000Z (about 2 years ago)
- Last Synced: 2024-05-01T17:11:47.896Z (about 2 years ago)
- Topics: actions, backlog, github-actions, hacktoberfest, nulab, nulab-backlog
- Language: TypeScript
- Homepage: https://bicstone.me/backlog-notify-v4
- Size: 2.47 MB
- Stars: 70
- Watchers: 3
- Forks: 14
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Backlog Notify
[](https://github.com/bicstone/backlog-notify/actions/workflows/ci.yml)
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fbicstone%2Fbacklog-notify?ref=badge_shield)
[](https://sonarcloud.io/dashboard?id=bicstone_backlog-notify)
[](https://deepsource.io/gh/bicstone/backlog-notify/?ref=repository-badge)
[](https://codecov.io/gh/bicstone/backlog-notify)
Notify commit messages to [Backlog.com](https://backlog.com/) issue.
GitHub 上のプッシュとプルリクエストを Backlog 課題に連携する GitHub Action です。キーワードによる課題の状態変更も可能です。
個人が開発した Action です。ヌーラボ様へのお問い合わせはご遠慮ください。
## 機能
### プッシュ
コミットメッセージの中に課題番号 (例: `PROJECT-123` ) がある場合は、その課題にコミットログに関するコメントを送信します。課題キーは先頭にある 1 つのみ認識します。
```plan
PROJECT-123 不具合修正
```
また、キーワードがある場合は、プッシュされたタイミングで課題ステータスを変更します。キーワードは末尾にある 1 つのみ認識します。
- `#fix` `#fixes` `#fixed` のどれかで処理済み
- `#close` `#closes` `#closed` のどれかで完了
```plan
PROJECT-123 不具合修正 #fix
```
※ 大量にプッシュするとそのまま投稿され、 Backlog に負荷がかかるのでご注意ください。
### プルリクエスト
プルリクエストのタイトルの中に課題番号 (例: `PROJECT-123` ) がある場合は、その課題にプルリクエストに関するコメントを送信します。課題キーは先頭にある 1 つのみ認識します。
```plan
PROJECT-123 不具合修正
```
また、キーワードがある場合は、マージされたタイミングで課題ステータスを変更します。キーワードは末尾にある 1 つのみ認識します。
- `#fix` `#fixes` `#fixed` のどれかで処理済み
- `#close` `#closes` `#closed` のどれかで完了
```plan
PROJECT-123 不具合修正 #fix
```
※ プルリクエストが Draft の状態である場合はコメント送信・ステータス操作をしません。
※ タイトルを変更した場合の通知は今のところ対応していません(対応予定)。Close → タイトルを変更 → Reopen を行うと通知されます。
## 設定方法
### Backlog API キーの取得
1. Backlog のプロジェクトに移動します。
1. プロジェクト設定 → 参加ユーザー → 新しいユーザの追加はこちらから を選択します。
1. クラシックプランの場合は `一般ユーザ` 、新プランの場合は `ゲスト` を選択します。
1. 登録します。
1. 登録した BOT アカウントにログインします。
1. 個人設定 → API → 登録 で API キーを発行します。
### API キーを GitHub に登録
1. GitHub のリポジトリページに移動します。
1. Setting → Secrets → Add a new secret を選択します。
1. Name は `BACKLOG_API_KEY` とし、 Value に API キーをそのまま貼り付けます。
1. 登録します。
### collaborator による workflow の実行を制限
プライベートリポジトリの場合は下記の操作を行う必要はありません。
パブリックリポジトリの場合は、collaborator からの workflow の実行を制限してください。
1. Setting → Actions → Fork pull request workflows from outside collaborators を開きます。
1. `Require approval for all outside collaborators` を選択します。
### Workflow の作成
GitHub Actions workflow を作成します (例: `.github/workflows/backlog-notify.yml` )。
```yaml
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](https://docs.github.com/ja/actions/using-workflows/workflow-syntax-for-github-actions#on) を参照に実行する条件を制御することができます。
また、コメントのフォーマットや、メッセージを解析する際の正規表現などをカスタマイズすることもできます。
```yaml
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](https://lodash.com/docs/4.17.15#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](https://lodash.com/docs/4.17.15#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](https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request) の Response schema をご参照ください。
User
[Get the authenticated user - GitHub Docs](https://docs.github.com/en/rest/users/users#get-the-authenticated-user) の Response schema をご参照ください。
#### `commit_message_reg_template`
コミットメッセージ解析の正規表現雛形を変更できます。
構文については [lodash/template](https://lodash.com/docs/4.17.15#template) をご参照ください。
使用可能な変数
| 変数名 | 型 |
| --------------- | -------- |
| `projectKey` | string |
| `fixKeywords` | string[] |
| `closeKeywords` | string[] |
#### `pr_title_reg_template`
プルリクエストタイトル解析の正規表現雛形を変更できます。
構文については [lodash/template](https://lodash.com/docs/4.17.15#template) をご参照ください。
使用可能な変数
| 変数名 | 型 |
| --------------- | -------- |
| `projectKey` | string |
| `fixKeywords` | string[] |
| `closeKeywords` | string[] |
## よくある質問と回答
- 何をプッシュしても実行に失敗し、ログに 401 エラーとある
API キーが誤っている可能性があります。
- プロジェクトキーと課題キーが正しいのに実行に失敗し、ログに 404 エラーとある
該当 API キーのユーザーがプロジェクトに参加していない可能性があります。
## 貢献
コントリビューターの皆様に感謝いたします。
Thanks goes to these contributors.
Oishi Takanori
🤔 💻 🚧 💬 📖 👀
takeshi.kondo
🐛 💻
Kenta SUZUKI
📖
mantaroh
🤔
Hyunjoon KIM
🤔 💻
Shuya Honda
🤔
貢献はいつでも大歓迎です。事前に [CONTRIBUTING.md](CONTRIBUTING.md) をご確認ください。
Contributions of any kind welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md).
## ライセンス
MIT License
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fbicstone%2Fbacklog-notify?ref=badge_large)