整理如何設定 git (github, bitbucket, gitlab) 與 Redmine Issue 整合.

這個目的是讓 commit 的東西跟 issue 做關聯性，可以讓相關人員知道到底改了些什麼？

這方法不需要另外安裝 Redmine Plugins, 設定分以下步驟：

• Git Repository 與 Redmine 同步 (系統管理者)
• 訊息關鍵字設定 (系統管理者)
• 專案設定 (專案負責人)

設定 Git Repository 與 Redmine 同步

因為 Redmine Repository 是讀取本機路徑，所以需要有個機制可以自動把 git 的資料同步到 Redmine 裡。

Mirror Repository to Local

先在 Redmine Server 裡建立一個目錄，用來放置 repository 的，像這樣：

1
2
3

mkdir -p /data/redmine/repos
cd /data/redmine/repos
git clone --mirror git@bitbucket.org:gtcafe/aws-notification.git

注意事項：

• git clone 記得要加 --mirror
• 通常會需要放一把 deployment key 到 bitbucket or github.
• 放置 repository 的空間要夠大，避免未來不足。建議是獨立的 storage，同時要有備份機制。

建立同步排程

每五分鐘自動同步一次，同步的頻率依照需求調整。

1
2

## 每五分鐘同步一次 repos, 依照需求自行增加
*/5 * * * * cd /data/redmine/repos/aws-notification.git && git fetch --all

Issue 關鍵字設定

Git 整合到 Redmine 有個很重要的目的：

1. 把 Issue 跟 Commit 關聯在一起，可以知道到底改了些什麼
2. 透過 Commit 的關鍵字，自動調整 Issue 的狀態

這兩個功能，可以讓開發、測試、PM 等相關人員，可以在 Issue 上完整知道程式與任務的關聯性、進度等。

此部分需要 Redmine Admin 權限

Issue 與關鍵字的關聯

開發者 commit 到 git 的時候，只要在註解寫入指定的關鍵字，那麼 Redmine 會自動把 Commit 跟 Issue 關聯在一起，像這樣：

1
2

~ $ git commit -m 'ref #69 init'
~ $ git push -u origin master

這個 commit 裡出現這樣的 pattern: ref #69 表示這次的 commit 要和 Issue #69 關聯在一起。前字詞 ref 是一定要的，可以自行設定，設定步驟如下：

• 到 Administration -> Settings -> Repository
• 找到 Referencing and fixing issues in commit messages -> 指定 Referencing keywords，可以多個

Issue 狀態與關鍵字同步

除了關鍵字可以跟 Issue 關聯，同時另外針對不同的 Tacker type 和不同的關鍵字匹配後，自動更新狀態和進度。常用的例子像是：

• 當完成 Feature 的時候，自動把狀態改成 Completed、進度改成 100% Done
• 當修正 Bug 的時候，自動把狀態改成 Resolved、進度改成 80% Done
• 每次的 Repository.fetch_changesets 執行時，就會比對符合關鍵字。這部分請參考『同步 Commit 異動』

我的設定值是這樣：

• 關鍵字: done, fixed, ref
• 關鍵字動作：
  • Tracker: Feature, keyword: done, Status: Completed, Done: 100%
  • Tracker: Bug, keyword: fixed, Status: Resolved, Done: 80%

如下圖：

同步 Commit 異動

Redmine 是 Web Application，像是 Commit 這種非同步需要透過其他方式驅動，把前述兩個動作要把關聯性連結起來。我用 crontab 每五分鐘執行更新，主要是執行 rails runner:

1
2

## 更新 repository 的異動
*/5 * * * * cd /home/redmine && ./bin/rails runner "Repository.fetch_changesets" -e production

註：如果無法正確執行，可能是 crontab 執行時無法取得 rails 需要的環境變數，可以透過 env 取得相關的變數，如果是 ubuntu，可以直接加入 crontab 裡，如下，如果使用 centos 可以寫一個 script 來驅動。

1
2
3
4
5
6
7
8
9
10

rvm_bin_path=/usr/local/rvm/bin
GEM_HOME=/usr/local/rvm/gems/ruby-2.0.0-p648
rvm_path=/usr/local/rvm
rvm_prefix=/usr/local
PATH=/usr/local/rvm/gems/ruby-2.0.0-p648/bin:/usr/local/rvm/gems/ruby-2.0.0-p648@global/bin:/usr/local/rvm/rubies/ruby-2.0.0-p648/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/rvm/bin
rvm_loaded_flag=1
GEM_PATH=/usr/local/rvm/gems/ruby-2.0.0-p648:/usr/local/rvm/gems/ruby-2.0.0-p648@global
RUBY_VERSION=ruby-2.0.0-p648
rvm_user_install_flag=0
*/5 * * * * cd /opt/redmine; ./bin/rails runner "Repository.fetch_changesets" -e production

設定專案裡的 Repository

建立 Issue

先到 Project 新增一個 Issue 作為 commit 的參考點，這個例子會產生 Issue Number: #69

第一次 commit

初始化 git repository, commit 時記得在註解用關鍵字 ref #69, 表示這次 commit 要跟 #69 綁住關聯

1
2

~ $ git commit -m 'ref #69 init'
~ $ git push -u origin master

設定專案 Repositories

Redmine 是 Project-Based ，所以每個專案都可以有多個 Repositories。以下設定需要 Project Admin 權限。

1. Project -> Settings -> Modules Tab -> Check Repository
2. Project -> Settings -> Repository Tab -> New Repository, 新增以下資訊

• Identifier: 識別關鍵字。每個專案可以有多個 Repos，如果要在 Issue 裡關聯 Commit，多個 Repos 的時候，就要指定識別字。預設可以不用給，但是第二個就要設定。
• Path to repository: Repos 的路徑，只能指定本機路徑。

到 Project -> Repository, 應該可以看到剛剛 commit 的 issue:

剛剛 commit 已經被關聯到 issue, 點選 #69 ，Issue 會出現以下：

Status Change for Feature / Bug

1. 建立另一個 Issue with Feature
2. 修改 Code, commit with comment: git commit -m 'done #70'
3. Feature #70 的狀態自動改為 Completed, Done 100%

如下圖：

下圖則是針對 Bug:

• 同樣的先改 Code, 然後 Commit with: git commit -m 'fixed #71'

3. Bug #71 的狀態自動改為 Resolved, Done 80%

Troubleshooting

Commit 沒有關連到 Issue?

1. 檢查 Project -> Repository: 是否已經 fetch，本文的設定是每五分鐘同步一次，參考：建立同步排程
2. Commit keyword 和 Issue 關聯式透過：同步 Commit 異動 驅動，可以手動驅動或者等待排成執行

後記

以前在 IBM 用的是 CMVC，他的設計就是 Issue Management + SCM ，所以我一直習慣 commit 要綁 Issue，如果 Issue 無法跟 SCM 綁在一起，就會覺得很奇怪。所以後來到另一個工作導入 Redmine (詳細參閱『協同合作系統建制與導入 - 以 Redmine 為例) 時，發現他可以做類似的事情，所以就跟以前同事一起搞定，不過那時候整合的是 SVN。

一直覺得做軟體開發，這是必要的。對團隊整體的協同合作、技術能力提升，很有幫助。這件事情隨著時間的拉長，會逐漸提升他的價值與重要性。

延伸閱讀 (站內)

系列文章

• 系統篇：
  • Redmine 安裝篇：Redmine 4.0.x on Ubuntu 16.04
  • 系統整合：Integrate GIT in Redmine
  • 如何透過 Email 建立 Issue
  • 系統整合：Redmine Plugins and Themes
• 概念篇：
  • 協同合作系統建制與導入 - 以 Redmine 為例
  • Issue Tracking in Redmine
  • 寫在介紹 Redmine 之前
  • 需求管理 (Requirement Management)
  • Software Development Lifecycle

參考資料

• Redmine Bitbucket plugin
• AWS上のRedmineでBitBucketのリポジトリを設定する