Redmineは日本国内で広く使われているオープンソースのプロジェクト管理ソフトウェアです。タスクなどを「チケット」に登録し、ガントチャートやカレンダーなどで表示させ、プライオリティなどを設定しプロジェクトの進捗をリッチな機能で管理することができます。プラグインを使った機能拡張も充実しており、GitHubと連携させGitHubのIssues機能とは別に使用することが出来ます。GitHubのIssueとRedmineのチケットを結び付けてステータスの同期を行ったり、GitHub内のリポジトリの変更点やその変更をしたユーザ情報などをRedmineから確認することが出来ます。
GitHubでは他のツールと統合するための仕組みとして、「GitHub Services」 または 「GitHub Webhooks」 という機能が使われてきました。しかし、そのうちの一つの「GitHub Services」機能のサポートが2018年10月に廃止されました。Redmineとの連携は「GitHub Services」が使われる事例がよくありますが今後は外部サービスとの連携の際は「GitHub Webhooks」で行う必要があるため、本記事では「GitHub Webhooks」機能を使ったRedmineとの連携方法についてご紹介します。
「GitHub Services」の廃止に向けてのタイムライン
～GitHub Enterprise～
GitHub Enterprise 2.17(2019年以降リリース予定)からGitHub Servicesのインストールや設定が出来なくなります。
～GitHub.com～
2018年10月1日：GitHub Servicesのインストールができなくなり、UIから削除されました。2019年1月31日：インストール済みのGitHub Servicesとの連携が出来なくなりました。
上図は、様々なツールに対応しているGitHub Servicesの設定画面。GitHub Enterprise 2.17以降は廃止。
Webhooksとは
WebhooksはGitHub上でのイベントを起点に、外部にHTTPでイベント内容を送ることが出来る機能です。Webhooksを送るイベントをRepositoryごとに設定することが出来ます。例えば、Gitのリポジトリにプッシュされた時やPull requestが作られた時などのイベント発生時に連携をしているツールにイベントを送ることが出来ます。
上図は、PushイベントにのみWebhookが送信されるように設定しています。
GitHubとRedmineを連携したらどんなことができるのか？
1. Redmine上でGitHub のCommit情報を閲覧することができます。
Commitの差分をRedmineで確認ができます。
2. GitHubでCommitする際にCommitメッセージに特定のキーワードを含めるとRedmineのチケットと紐付けすることができます。（下図の”refs”キーワードはRedmineで予め認識するように設定してあります）
GitHubで以下のようにCommitをすると、
RedmineチケットにCommitが表示されるようになります。
3. GitHubでCommitする際にCommitメッセージにキーワードを含めるとRedmineのチケットのステータスを変更することも出来ます。（以下の”Close”キーワードはRedmineで予め認識するようにしてあります）
GitHubで前項同様にCommitをすると、
Redmineチケットのステータスが変更されます。
GitHub と Redmineの連携設定手順
ここではGitHub EnterpriseとRedmineを連携するために必要な設定などをご説明します。
前提
- Unix/LinuxでRedmine 2.0以上のインストール
- 最新のGit
最新版のGitRedmine GitHub Hookプラグインのインストール
1. Redmineがインストールされているサーバで作業します。
2. Redmineのディレクトリに移動し、localファイルにgem "redmine_github_hook" を下図のように追記します。
Gemfile.localまたはGemfile
3. bundleコマンド実行します。
4. Redmineサービスを再起動します。
5. プラグインのインストール状態を確認します。
http(s)://[redmine-hostname]/admin/plugins
Redmineの設定
1. Redmineのサーバにredmineユーザで接続します。
2. Gitリポジトリを管理させるディレクトリに移動します。
3. GitHub Enterpriseのリポジトリを”mirror”オプション付きでCloneします。
$ git clone --mirror git@[github-hostname]:owner/repository.git
※注意事項
gitはSSHプロトコルでの接続が必須となるのでご注意ください。もし、git cloneに失敗する場合はユーザがリポジトリのRead権限を与えられているかご確認ください。
・SSH鍵をGitHubのユーザに登録していない場合は以下の方法で作成します。
1. Redmineホスト端末にてパスワード無しのSSH鍵の生成する
ssh-keygen -t rsa -b 4096 -C your_email@example.com
2. 生成されたSSH公開鍵 (id_rsa.pub)の中身をGitHubアカウントに登録する
http(s)://[github-hostname]/settings/keys
3. Redmineのサーバにてgit cloneを実行し動作確認します
$ git clone --mirror git@[github-hostname]:git_user/project.git
$ cd project.git
$ git fetch -q --all -p
上手くプラグイン(Redmine GitHub Hook)が動作しない場合は、プラグインの公式ページ (英文) などで確認も出来ます。
https://github.com/koppen/redmine_github_hook
RedmineにGitHubリポジトリの追加
1. Redmineのプロジェクトを選択、または新規で作成します。
2. プロジェクトの設定にて新しいリポジトリを作成します。
リポジトリのパスはGitのリポジトリのパスを入力します。
GitHubの設定
1. リポジトリの設定に移動し、Webhookを追加します。設定にはリポジトリのAdmin権限が必要です。
2. Payload URLは次のフォーマットで入力します。
http://[Redmine-hostname]/github_hook?project_id=[Redmine-projectname]
“Which events would you like to trigger this webhook?” の項目ではWebhookが送信されるイベントを指定します。今回はPushイベントのみ設定します。
3. Webhookを登録後はテストWebhookが送信されるため、同じ画面にて“Recent Deliveries”から正しく送信されているかを確認します。
動作確認
1. Commitをします。
2. RedmineにそのCommitが反映されます。
リビジョン
「最新リビジョン」でCommitの差分が確認できます。
チケットとCommitの結び付け
GitHubのCommitメッセージに「refs,references,IssueID」いずれかのキーワードとチケット番号を含めるとRedmine上のチケットとCommitを結び付けすることができます。
1. トップの「管理」⇒「設定」でキーワードの確認と設定ができます。
2. Commitメッセージに「refs #チケット番号(Redmine)」を含めてCommitをします。
-4.jpg?width=419&name=refs%20%23%E3%83%81%E3%82%B1%E3%83%83%E3%83%88%E7%95%AA%E5%8F%B7(Redmine)-4.jpg)
3. するとRedmineのチケットの「関係しているリビジョン」に紐付けされたCommitが表示されます。
チケットのステータス変更
Commitメッセージに指定したキーワードを含めるとRedmineチケットのステータスを変更することができます。
1. Redmineのトップの「管理」⇒「設定」でキーワードとステータスを指定できます。
2. Commitメッセージに指定したキーワード「Close #Redmineチケット番号」を含めます。
3. するとRedmineのチケットのステータスが変更されます。
4. ステータスの種類は「新規、進行中、解決」などがあるため、それぞれお試しください。
GitHubとRedmineのWebhooksを使った連携方法は以上になります。
