跳轉到內容

Phabricator 管理員手冊/持續整合

Add links
來自華夏公益教科書
擷取 Phabricator 歷史頁面中一些“已透過”和“已失敗”的螢幕截圖。

Phabricator 可以配置為支援一些 持續整合 (CI) 工作流程，這得益於一個名為 Harbormaster 的元件。

開始閱讀官方的 Harbormaster 使用者指南，以瞭解一些重要的通用概念。

你需要什麼

[編輯 | 編輯原始碼]
  • 1/2 小時
  • 瞭解 Phabricator 的 Diffusion 元件（處理您的儲存庫的元件）

安裝

[編輯 | 編輯原始碼]

Harbormaster 已經是 Phabricator 的一部分，但預設情況下不會顯示。它是一個原型應用程式。

檢視如何啟用原型應用程式

https://secure.phabricator.com/book/phabricator/article/prototypes/

前言

[編輯 | 編輯原始碼]

通常，剛開始使用內部持續整合的使用者只是想 對提交做出反應並執行命令，但這極其簡化，而且可能變得危險。

這就是為什麼新的 Phabricator 使用者常常驚訝地發現 Phabricator 不允許這種“超級簡單”的解決方案。這很好，因為在能夠犯大錯誤之前，我們需要閱讀一些文件。

安全問題

[編輯 | 編輯原始碼]

首先，不要嘗試在您的工作儲存庫上執行直接命令。永遠不要。這可能會破壞該儲存庫，而且您還可能最終損害整個 Phabricator 基礎設施。

花一些時間實施一個標準的乾淨解決方案，以確保您的儲存庫安全無虞指令碼破壞，並且不以相同的 Phabricator 許可權執行這些指令碼。例如，在其他機器上執行指令碼，在其他工作副本上執行指令碼，並且始終使用低許可權的臨時使用者執行指令碼，而不是與 Phabricator 相關的使用者。

閱讀 Drydock 安全官方文件，以獲取更多說明。

設定解決方案

[編輯 | 編輯原始碼]

為了非常籠統地說，您有兩種選擇

  1. 配置 Phabricator 以連線到一些 SSH 伺服器並從那裡完成所有操作（克隆、構建等）
  2. 將構建委派給其他服務

第一種解決方案很有趣，因為它允許您使用自己的基礎設施。這可以透過使用名為 Drydock 的 Phabricator 元件來配置。

第二種解決方案只需呼叫外部服務的 API。如果您已經擁有構建系統，例如 Jenkins，這將很有趣。

設定 1：在自己的硬體上（使用 Drydock）

[編輯 | 編輯原始碼]
Phabricator 中使用 Drydock 的持續整合流程。

您可以配置 Phabricator 的 Harbormaster 元件以使用您自己的硬體構建內容，這得益於一個名為 Drydock 的元件。Drydock 分配您的資源。

以下是實際工作示例的完整流程

  1. 開發人員執行 git push 以將本地編輯釋出到 Phabricator（或使用 Phabricator 支援的其他源版本控制工具，例如 Subversion 或 Mercurial）
  2. Phabricator 檢查該提交是否觸發了規則，並最終執行操作。Herald 元件定義了這些規則。
  3. 匹配了一個 Herald 規則，並且操作是在 Harbormaster 中配置的“構建計劃”。它開始執行其步驟。
  4. 構建計劃的第一個步驟可能是請求一個工作副本（我們說，我們“租用”一個工作副本——因為我們不直接處理 Diffusion 使用的相同儲存庫，而只是獲取或建立另一個副本）
  5. Drydock 元件提供該工作副本，檢查是否有可用的主機具有已準備好的工作副本。它透過您配置的 Almanac 目錄瞭解您的配置基礎設施。
  6. 構建計劃的下一步可以是“在該工作副本上執行命令”（從技術上講，它在“Drydock 租用”上執行命令）
  7. 如果命令成功退出，您將在您的提交旁邊看到一個 已透過 標記，否則將看到 已失敗 標記。

讓我們開始實施它。

我們首先建議您閱讀來自 Phabricator 討論論壇的這個 示例配置。

描述您的網路和裝置

[編輯 | 編輯原始碼]

首先，您需要在 Almanac 目錄中描述一些裝置。

我們所說的“裝置”是什麼

  • 一個可以透過 SSH 訪問的物理伺服器
  • 一個虛擬伺服器（VPS、Docker 執行、虛擬機器等），可以透過 SSH 訪問

您知道您要為構建系統專門分配哪種裝置。它可能是一個虛擬伺服器，也可能恰好是您的同一臺伺服器（但使用低許可權的使用者）。

現在，讓我們在您的 Almanac 目錄中對其進行描述：[1]

  1. 定義一個 Almanac 網路：您必須至少有一個網路。常見的名稱是“公共”或“私有”或“本地網路”。您的伺服器將與之關聯。
  2. 定義一個 Almanac 裝置：為要為構建系統專門分配的第一臺伺服器指定一個名稱。該伺服器應可以透過 SSH 從 Phabricator 訪問，因此請單擊 新增介面，選擇之前的網路，插入其 IP 地址/域名，然後鍵入標準 SSH 埠 22。
  3. 定義一個 Almanac 服務：開啟 Almanac 並定義一個服務，選擇 Drydock：資源池 作為服務型別。這將是可用伺服器的容器，因此名稱可以是“構建伺服器池”。單擊“新增繫結”並選擇之前的裝置。

準備您的構建伺服器

[編輯 | 編輯原始碼]

此時，您應該已經確定好要用於構建系統的伺服器。您應該知道如何透過 SSH 連線到該伺服器（如果不知道，請閱讀 SSH 手冊）。

確保您可以使用 SSH 公鑰連線到您的伺服器（提示：為此目的建立一個額外的 SSH 金鑰，因為您需要將相關的私鑰釋出到 Phabricator 中，以允許它連線到您的伺服器）。

ssh foobot@server_build_01

進入您的伺服器後，確保您有權克隆您的倉庫。嘗試克隆您的倉庫之一。如果您的倉庫是公開的，那麼您就可以正常操作。相反，如果您的倉庫受到一些可見性限制，則應該建立一個專門的 Phabricator 機器人（機器人是型別為“機器人”的使用者）並將該使用者放在正確的專案中。您可以從 Phabricator 使用者頁面建立機器人。例如，機器人可以被稱為“Foo Bot @ server_build_01”，您必須將其新增到正確的專案中，以允許該使用者讀取您的倉庫。

您可能希望從伺服器生成一個 SSH 金鑰，並在其使用者首選項（您剛剛建立的機器人的使用者首選項）中釋出其公鑰。簡而言之，確保您可以從您選擇的使用者（foobot）使用標準的 Phabricator 授權從您的伺服器克隆您的倉庫。

提示：實際上，您選擇的使用者（foobot）應該能夠寫入 /var/drydock 目錄以克隆工作副本。[2]

從 Drydock 主機文件 中瞭解更多資訊。

設定 Drydock 藍圖

[編輯 | 編輯原始碼]
包含藍圖和資源的 Drydock 選單

現在您應該定義幾個“藍圖”。藍圖是 Drydock 元件要達成的“目標”。請先閱讀 Drydock 藍圖文件。

簡而言之，您需要配置兩個 Drydock 藍圖：[3]

  1. 建立一個型別為 Almanac 主機 的藍圖 - 此藍圖將選擇可用的主機，因此示例名稱可以是“主機租用器”。在 Almanac 服務 欄位中，選擇您建立的服務（可能稱為“Buildservers 池”）。請記住設定一個有效的 SSH 公鑰以訪問主機，如 #準備您的構建伺服器 中所述。
  2. 建立一個型別為 工作副本 的藍圖 - 此藍圖將提供工作副本，因此示例名稱可以是“來自 Buildservers 池的工作副本租用器”。在 使用藍圖 欄位中，選擇之前建立的藍圖（可能稱為“主機租用器”）。

現在從 Phabricator 的根目錄執行此命令

./bin/drydock lease --type host

您應該會看到類似的輸出

$ ./bin/drydock lease --type host
Queued lease for activation:

        https://example.com/drydock/lease/1/

Waiting for daemons to activate lease...
<Lease Queued> Lease queued for acquisition.
<Lease Acquired> Lease acquired.
<Lease Activated> Lease activated.
Activation complete. This lease is permanent until manually released with:

        $ ./bin/drydock release-lease --id 1

Lease activated in 2,277ms.

您可以進一步閱讀 Drydock 工作副本官方文件 以獲取更多說明。

設定 Harbormaster 構建計劃

[編輯 | 編輯原始碼]

現在進入 Harbormaster 頁面，然後單擊“建立構建計劃”[4]。

新增兩個構建步驟

  1. 建立一個型別為 租用工作副本 的構建步驟。在 使用藍圖 欄位中，選擇之前建立的 Drydock 工作副本藍圖（可能稱為“來自 Buildservers 池的工作副本租用器”）。示例名稱可以是“從 Buildservers 池租用工作副本”。工件名稱 是此步驟產生的內容，因此示例名稱可以是“從 Buildservers 池租用的工作副本”。
  2. 建立一個型別為 Drydock：執行命令 的構建步驟。在 Drydock 租用 欄位中，輸入與上一步的 工件名稱 欄位中輸入的值相同的值（可能稱為“從 Buildservers 池租用的工作副本”。在 命令 欄位中，鍵入將在您的倉庫中執行的命令。

提示：命令的工作目錄將是工作副本的路徑名。您不應該嘗試預測其完整的路徑名，因為它是在內部生成的。

提示：工作副本將克隆到 /var/drydock[2] 中。

提示：該命令將以您在 #準備您的構建伺服器 中準備的 SSH 使用者的許可權執行。

在事件之後執行構建計劃

[編輯 | 編輯原始碼]
一個 Herald 規則觸發構建計劃的示例。
另請參閱：Phabricator 管理員手冊/Herald

現在您可能希望配置 Phabricator 在事件之後自動執行構建計劃。例如

設定 Herald 以對提交進行反應
[編輯 | 編輯原始碼]

您可能希望在有人對倉庫進行提交時自動執行構建計劃。在這種情況下

  1. 開啟 Herald 元件的主頁，然後單擊 建立 Herald 規則[5]
  2. 選擇 新建規則目標：提交
  3. 選擇 規則型別：物件 - 為了將您的 Herald 規則附加到特定的倉庫
  4. 鍵入您的倉庫程式碼 - 請注意，它以大寫的 R 開頭，類似於 R123[6]
  5. 在 條件 欄位中，您可能希望選擇 始終
  6. 在 操作 欄位中，您可能希望新增 執行構建計劃 並選擇您的構建計劃。
設定 Herald 以對 Differential 修訂進行反應
[編輯 | 編輯原始碼]
具有配置的外部暫存區的 Diffusion 倉庫示例。

您可能希望在有人從 Differential 提出補丁時自動執行構建計劃。

在 Phabricator 中，使用者可以為倉庫提出補丁（Differential 修訂）。使用者可以使用名為 Arcanist 的命令列工具（使用命令 arc diff）提交此補丁。然後，您可能希望檢查此補丁在合併（落地）到您的倉庫後是否會破壞一切。

此方法的問題在於，您無法在這種情況下執行構建計劃。事實上，此時您還沒有包含該補丁的倉庫。

這就是為什麼此解決方案類似於 #設定 Herald 以對提交進行反應，但我們需要引入一個 暫存區。

以下是步驟

  1. 建立一個新的倉庫（它可以位於 Diffusion 中，也可以不在 Diffusion 中），並確保普通使用者有權向其中推送程式碼。這將是您的 暫存區。
  2. 現在返回到您的原始倉庫，並開啟其 Diffusion 頁面。編輯它，您應該會注意到一個 暫存區 選單。從該頁面貼上您的新倉庫的 URL[7]
  3. 開啟 Herald 元件的主頁，然後單擊 建立 Herald 規則[5]
  4. 選擇 新建規則目標：Differential 修訂
  5. 選擇 規則型別：全域性
  6. 在“條件”欄位中，您可能需要選擇“儲存庫專案”，並選擇“包含任何”選項，然後選擇您的專案。
  7. 在 操作 欄位中，您可能希望新增 執行構建計劃 並選擇您的構建計劃。

另請參閱 官方Harbormaster文件 中關於“手動暫存區”的“更改移交”部分。

方案 2：使用外部服務

[編輯 | 編輯原始碼]
Jenkins 儀表板，一個外部服務的示例。

另一種常見解決方案是使用 Phabricator 之外的外部構建服務。如果您已經熟悉外部構建服務，此解決方案可能會更好。

請注意，在呼叫外部服務時，Phabricator 可能無法等待輸出（因為 Phabricator 向您的外部服務傳送 HTTP 請求，但顯然該服務不會在該短請求結束時結束構建）。因此，您可能還需要配置另一個小型守護程式來查詢您的外部服務，等待您的構建，並最終通知 Phabricator 該構建狀態。

一些不完全的資源列表

故障排除

[編輯 | 編輯原始碼]

以下是您在實施 #方案 1：在自己的硬體上使用 Drydock 後可能會看到的一些常見錯誤。

故障排除“租賃 PHID-... 從未啟用”

[編輯 | 編輯原始碼]

如果您看到錯誤“租賃 PHID-... 從未啟用”或類似的堆疊跟蹤

PhabricatorWorkerPermanentFailureException: Lease "PHID-..." never activated. in .../phabricator/src/applications/harbormaster/step/HarbormasterLeaseWorkingCopyBuildStepImplementation.php:91
Stack trace:
#0 .../phabricator/src/applications/harbormaster/worker/HarbormasterTargetWorker.php(70): HarbormasterLeaseWorkingCopyBuildStepImplementation->execute(Object(HarbormasterBuild), Object(HarbormasterBuildTarget))
#1 .../phabricator/src/infrastructure/daemon/workers/PhabricatorWorker.php(124): HarbormasterTargetWorker->doWork()
#2 .../phabricator/src/infrastructure/daemon/workers/storage/PhabricatorWorkerActiveTask.php(158): PhabricatorWorker->executeTask()
#3 .../phabricator/src/infrastructure/daemon/workers/PhabricatorTaskmasterDaemon.php(22): PhabricatorWorkerActiveTask->executeTask()
#4 .../libphutil/src/daemon/PhutilDaemon.php(219): PhabricatorTaskmasterDaemon->run()
#5 .../libphutil/scripts/daemon/exec/exec_daemon.php(131): PhutilDaemon->execute()
#6 {main}

再次檢查 #設定 Drydock 藍圖 並檢視您的藍圖日誌。您可能尚未啟用任何主機。

故障排除“資源啟用失敗：[CommandException] 命令失敗，錯誤程式碼為 #128！”

[編輯 | 編輯原始碼]

如果您看到此錯誤或類似的錯誤

Resource activation failed: [CommandException] Command failed with error #128!
COMMAND
ssh '-o' 'LogLevel=ERROR' '-o' 'StrictHostKeyChecking=no' '-o' 'UserKnownHostsFile=/dev/null' '-o' 'BatchMode=yes' -l ...

STDOUT
(empty)

STDERR
LOT OF ERRORS HERE

仔細檢視 STDERR 部分

故障排除“無法建立目錄 .ssh”

[編輯 | 編輯原始碼]
  • 如果您有

無法建立目錄“.../.ssh”

這意味著 Phabricator 使用者守護程序正在嘗試使用 SSH 連線到您的構建伺服器，因此它需要一個可寫的 $HOME/.ssh 目錄來寫入 $HOME/.ssh/known_hosts 檔案等。Phabricator 使用者守護程序的主目錄可能不可寫。

如果您不知道您的 Phabricator 使用者守護程序是什麼，它是執行您的守護程序的守護程序。您在 安裝 過程中設定了它。

故障排除“無法建立 /var/drydock 的前導目錄”

[編輯 | 編輯原始碼]

如果您有

could not create leading directories of '/var/drydock/...': Permission denied

構建內容的使用者無法寫入 /var/drydock，或者該路徑不存在。請再次閱讀 #準備您的構建伺服器 部分。請注意，該路徑實際上是無法自定義的。[8]

故障排除“致命錯誤：無法從遠端儲存庫讀取”

[編輯 | 編輯原始碼]

如果您有

fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.

返回到 #準備您的構建伺服器 部分。登入到您的構建伺服器並嘗試從其中克隆儲存庫。您可能需要在 Phabricator 中使用專門的機器人帳戶授權伺服器使用者，並配置 SSH 金鑰。

備註

[編輯 | 編輯原始碼]
  1. ↑ 在 Phabricator 搜尋框中搜索“Almanac”，或訪問 example.com/almanac/，可以找到 Almanac 庫存。
  2. ↑ a b 實際上，Drydock 被硬編碼為寫入 /var/drydock 中。有關更多詳細資訊，請參閱 T10664 和 T9492。
  3. ↑ 在 Phabricator 搜尋框中搜索“Drydock”，或訪問 example.com/drydock/，可以找到 Drydock 頁面。
  4. ↑ 在 Phabricator 搜尋框中搜索“Harbormaster”，然後單擊“構建計劃”，或訪問 example.com/harbormaster/plan/，可以找到構建計劃。
  5. ↑ a b 在 Phabricator 搜尋框中搜索“Herald”，或訪問 example.com/herald/，可以找到 Herald 元件。
  6. ↑ "Herald rule of type object for repository uppercase "R"". Phabricator Discussion Forum.
  7. ↑ 您可以透過訪問 Diffusion 儲存庫的公共頁面，然後單擊“管理儲存庫”→“暫存區”，或訪問 example.com/source/REPO_NAME/manage/staging/，來訪問該儲存庫的“暫存區”。
  8. ↑ "Can an alternate drydock (something other than /var/drydock) area be configuable". {{cite web}}: Unknown parameter |published= ignored (help)
檢索自 "https://wikibook.tw/w/index.php?title=Phabricator_Administrator%27s_Handbook/Continuous_integration&oldid=4243440"
華夏公益教科書