系統整合:Integrate GIT in Redmine


整理如何設定 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'
  1. 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。

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


延伸閱讀 (站內)

系列文章

參考資料


Comments