設定專案版本管控設定

本頁說明如何設定專案元素，以便與 Git 整合進行版本控管。

專案設定

如要查看專案設定，請開啟專案，然後從 Looker IDE 圖示選單中選取「設定」圖示。

您可以在這裡存取三個「專案設定」分頁：

設定

「專案設定」頁面的「設定」分頁會開啟「專案設定」頁面。在「專案設定」頁面中，您可以設定下列項目：

  • 名稱：專案名稱。如要重新命名專案，請編輯文字，然後按一下「儲存專案設定」按鈕。詳情請參閱「存取及編輯專案資訊」說明文件頁面。

  • Git 生產環境分支版本名稱：指定要用做專案開發分支版本合併目標的 Git 分支版本名稱。Git 分支版本必須存在於 Git 存放區中。詳情請參閱本頁的「Git 生產環境分支名稱」一節。

  • 程式碼品質：決定是否要要求開發人員先在專案中成功執行 LookML 驗證器，再將任何變更提交至專案。「程式碼品質」選項包括：

    • 提交前必須解決錯誤和警告：Looker 開發人員必須先成功執行 LookML 驗證工具，並解決所有錯誤和警告，才能提交變更。這是建議設定。
    • 提交前僅須解決錯誤：Looker 開發人員必須先成功執行 LookML 驗證工具並解決所有錯誤，才能提交變更。即使有警告，開發人員仍可提交變更。雖然不建議使用這個選項，但如果 Looker 更新後，工作中的 LookML 導入了新的警告，這個選項就很有用。
    • 允許提交有問題的程式碼：Looker 開發人員可以提交變更，不必執行 LookML 驗證器，也不必理會 LookML 中是否有錯誤或警告。不建議使用這個選項，因為這可能會導致 LookML 無法運作或產生錯誤結果。

  • 必須先通過資料測試，才能將這項專案部署至正式環境：如果 LookML 專案有一個或多個 test 參數，開發人員必須先執行資料測試，才能部署任何變更。如果資料測試通過，IDE 會允許開發人員將變更部署到正式環境。如要瞭解如何在 LookML 專案中設定資料測試，請參閱 test 參數說明文件頁面。如要瞭解如何在專案中執行資料測試，請參閱「使用版本管理和部署」說明文件頁面。根據預設，新 LookML 專案會啟用「必須先通過資料測試，才能將這項專案部署至正式環境」選項。

  • Git 整合：指定與 Git 供應商的整合層級。詳情請參閱「Git 整合選項」。

  • 啟用進階部署模式：啟用這項設定後，使用者就能將任何 SHA、標記或分支版本部署到實際工作環境。如要進一步瞭解如何使用版本管理功能並啟用進階部署模式，請參閱「進階部署模式」說明文件頁面。

  • Webhook 部署密鑰：設定驗證，將變更部署至 Looker 執行個體的正式版。詳情請參閱「設定 Webhook 部署密鑰」說明文件頁面。

  • 重設 Git 連線：這個按鈕會開啟「設定 Git」視窗，您可以在其中更新 Git 存放區的連線設定。

  • 刪除開發人員副本：如果不再需要 LookML 專案的開發人員 (本機) 副本、Git 狀態不一致，或無法編輯 LookML 檔案，請按一下這個按鈕刪除副本。如果刪除專案的開發人員副本，您尚未提交並推送至遠端存放區的任何變更，以及您建立的任何 Git 分支版本 (如果您尚未提交並推送該分支版本的變更)，都會遺失。詳情請參閱「使用版本管控和部署」說明文件頁面。

  • 刪除專案：這個按鈕會刪除專案，並從 Looker 執行個體的所有開發和正式環境中移除專案的所有 LookML。

  • Git 摘要：這個部分會顯示專案的 Git 設定，以及目前使用者的 Git 分支版本資訊。

Git 正式版分支名稱

使用預設的 Looker Git 整合功能時，所有 Looker 開發人員都會將變更合併至主要分支版本，通常稱為 main 或 master。您可以使用「Git 生產環境分支名稱」欄位，指定 Looker 應將 Looker 開發人員的分支合併至哪個 Git 存放區分支。(如需預設 Git 工作流程，以及進階 Git 實作的其他選項，請參閱「使用版本控管和部署」說明文件頁面)。

如果是現有專案，建議您先執行下列操作，再變更 Git 生產環境分支名稱：

  • 請 Looker 專案中的所有開發人員提交變更，並將分支版本合併至現有的正式環境分支版本，然後暫停工作，直到 Git 正式環境分支版本名稱更新並儲存至 Looker 專案設定為止。
  • 如果專案使用整合式提取要求，請視需要完成並合併所有未完成的提取要求。
  • 在 Git 供應商端執行任何必要準備作業，例如在存放區中建立新分支、重新命名現有的預設 Git 分支，或執行任何必要動作來準備分支，以便 Looker 可將其做為合併的目標分支。至少要確認您想使用的分支版本是 Git 存放區中的現有分支版本。

如要變更專案使用的 Git 分支，做為開發分支的合併目標，請按照下列步驟操作：

  1. 從 Looker IDE 圖示選單中選取「設定」圖示，即可顯示專案設定。系統預設會開啟「設定」分頁。
  2. 在「Git Production Branch Name」(Git 生產環境分支名稱) 欄位中，輸入要用做 Looker 專案生產環境分支的 Git 分支名稱。
  3. 按一下「儲存專案設定」按鈕，儲存變更。

匯入憑證

您可以在「Import Credentials」(匯入憑證)部分管理私有遠端存放區的驗證憑證。詳情請參閱「從其他專案匯入檔案 」說明文件頁面。

分支版本管理

在「專案設定」頁面的「分支管理」分頁中，您可以查看與專案相關聯的所有 Git 分支。詳情請參閱「使用版本管控和部署」說明文件頁面。

Git 整合選項

設定 Git 連線後，Looker 會使用 Git 供應商管理 LookML 來源檔案，如「使用版本管控和部署」說明文件頁面所述。

如果您是 Looker 管理員，可以使用專案設定面板「設定」分頁中的「Git 整合」選項，設定 Looker 與 Git 整合的其他選項：

  • 關閉：Looker 不會顯示任何前往 Git 供應商介面的外部連結。
  • 顯示連結：Looker 會提供 Git 供應商介面的外部連結，方便開發人員在 Git 供應商介面中查看專案。Looker 也會提供每個專案檔案的連結，方便開發人員在 Git 供應商的介面上查看檔案記錄和 Git blame 資訊。如要瞭解連結，請參閱「將外部連結整合至 Git 供應商」一節。
  • 建議使用提取要求：除了提供Git 供應商介面的外部連結，Looker 還會讓開發人員提交提取要求，以便其他開發人員在將變更新增至專案前核准變更。如要瞭解如何設定這項功能，請參閱「整合專案的提取要求」一節。
  • 需要提取要求：這與「建議提取要求」相同，但 LookML 開發人員必須開啟提取要求，才能將變更提交至專案。如要瞭解如何設定這項功能，請參閱「整合專案的提取要求」一節。

如要儲存 Git 整合設定，請按一下「Deployment」(部署) 部分下方的「Save Project Configuration」(儲存專案設定)。

如果您已啟用任何額外的 Git 整合選項 (「顯示連結」、「建議提取要求」或「需要提取要求」)，Looker 會提供 Git 供應商介面的外部連結。這些外部連結會在新瀏覽器分頁中開啟 Git 供應商的網站。

在每個 LookML 檔案的三點「檔案選項」選單中，Looker 會提供 Git 供應商網站的連結，方便您查看檔案、檔案的 Git 責任資訊，以及檔案的提交記錄。

在「Git Actions」面板中，您也可以使用「View Project on <Git provider>」選項，在 Git 供應商的網站上開啟專案檔案。

整合專案的提取要求

使用預設的 Looker Git 整合功能時，Looker 開發人員會將變更提交至開發分支版本，然後將開發分支版本合併至正式分支版本。然後，當您部署至 Looker 環境時，Looker 會使用 production 分支的最新提交內容。(如需預設 Git 工作流程，以及進階 Git 實作的其他選項，請參閱「使用版本控管和部署」說明文件頁面)。

您可以為專案設定「建議使用提取要求」或「必須使用提取要求」選項，禁止 Looker 開發人員將開發分支合併至 Looker 生產分支：

  • 建議使用提取要求：開發人員將變更提交至開發分支版本後，Looker IDE 中的 Git 按鈕會提示開發人員開啟提取要求，將開發分支版本合併至正式版分支版本。接著，開發人員可以透過 Git 供應商的網頁介面開啟提取要求，供其他 Looker 開發人員審查及核准。或者，開發人員也可以使用 Git Actions 面板中的「Deploy to Production」選項，略過建立提取要求的步驟，直接將變更部署到正式環境。(如果專案已啟用進階部署模式，則無法使用「部署到正式環境」選項)。
  • 需要提取要求：開發人員將變更提交至開發分支版本後，Looker IDE 中的 Git 按鈕會提示開發人員開啟提取要求。開發人員必須開啟提取要求，將開發分支合併至正式版分支。接著，其他 Looker 開發人員可以透過 Git 供應商的網頁介面，審查及核准提取要求。

Looker 支援下列 Git 供應商的提取要求整合：

  • GitHub
  • GitLab
  • Bitbucket Cloud
  • Bitbucket Server (舊稱「Stash」)

以下是使用 Looker 的提取要求時，需要注意的其他事項：

  • 如要開啟提取要求，開發人員必須擁有 Git 供應商的帳戶，且有權存取專案的 Git 存放區。

  • 如果執行個體已啟用「IP 位址許可清單」功能，如要將提取要求與任何 LookML 專案整合，您必須將 Git 供應商傳送輸出要求的 IP 位址範圍新增至許可清單。舉例來說，GitHub 變更記錄中列出了目前的 GitHub IP 位址。IP 位址可能會變更，且其他 Git 供應商的 IP 位址會有所不同。

  • 如果您已啟用進階部署模式，則不需要在「透過整合式提取要求設定專案」一節中設定 Webhook，因為進階部署模式會將合併和部署函式分開。

  • 如果 Looker 開發人員已發出提取要求，但您想還原，請參閱這篇 GitHub 社群文章，瞭解如何透過 GitHub 從 Looker 還原提取要求。

  • Git 提取要求可讓您使用 Looker 的測試環境執行個體，因此您可以同時擁有測試環境執行個體和正式版執行個體，並在測試環境執行個體中啟用提取要求。所有開發和程式碼審查作業都可以在暫存環境中完成，審查過的程式碼隨後可部署至正式執行個體。如要進行這項設定，請參閱「Git Workflow Using One Repository Across Multiple Instances — Development, Staging, and Production」社群貼文。

  • Looker 會使用合併的合併提交方法，將 Looker 開發人員分支版本的變更合併至正式版分支版本。使用 Git 供應商的介面時，請確保開發人員不會使用合併壓縮或變基合併。詳情請參閱「在 Git 供應商介面中合併選項」一節。

設定專案並整合提取要求

如要使用 Git 提取要求設定 Looker 專案，請按照下列步驟操作：

  1. 在專案中，從 Looker IDE 圖示選單選取「設定」。
  2. 在「設定」分頁的「Git 整合」部分，選取「建議使用提取要求」或「必須使用提取要求」。
  3. 如要在 Git 供應商的介面上設定自動部署 Webhook，請複製 Webhook 資訊並貼到文字檔中。如果專案已設定為使用進階部署模式，則可略過這個步驟。您也可以稍後再決定，然後返回專案設定取得 Webhook 資訊。
  4. 您也可以選擇設定 Webhook 部署密鑰，驗證來自 Git 供應商的自動部署 Webhook，或進階部署模式 Webhook。如要建立 Webhook 密鑰，請按一下「Set Webhook Secret」(設定 Webhook 密鑰)。複製部署密碼並貼到文字檔中，以便在將 Webhook 新增至 Git 供應商的介面時使用。您也可以稍後再決定，然後返回專案設定新增部署密鑰。詳情請參閱「設定 Webhook 部署密鑰」說明文件頁面。
  5. 按一下「儲存專案設定」。

現在，只要 Looker 開發人員將變更內容提交至專案，Looker IDE 就會顯示「開啟提取要求」按鈕。按鈕會直接在新瀏覽器分頁中，開啟 Git 供應商網站上的新提取要求頁面。

設定 Looker 專案以使用提取要求後，請執行下列其中一項操作，設定如何將提交內容部署至正式環境：

  • 如要自動部署合併至正式版分支的最新提交內容，請使用 Git 供應商的介面新增 Webhook，詳情請參閱本頁下一節。
  • 如要手動指定要部署的分支或提交內容，請啟用進階部署模式。如要瞭解如何啟用及管理進階部署模式，請參閱進階部署模式說明文件頁面。

在 Git 供應商中新增 Webhook

如果 Looker 專案已啟用提取要求，您可以在 Git 供應商的介面上設定部署 Webhook。每當您在 Git 供應商的介面上合併提取要求時，這個 Webhook 就會觸發 Looker 從正式版分支部署最新修訂版本。

如要在 Git 供應商的介面上新增自動部署 Webhook，請先前往 Looker 中的專案設定，方法是點選專案 Looker IDE 圖示選單中的「設定」圖示。接著，從「Git Integration」部分複製 Webhook。

Webhook 的格式為 <instance_url>/webhooks/projects/<project_name>/deploy。

將 <instance_url> 替換為 Looker 執行個體的網址。舉例來說，如果 Looker 執行個體網址為 example.looker.com，且專案名稱為 e_faa，則 Webhook 會如下所示：

https://example.looker.com/webhooks/projects/e_faa/deploy

您也可以在 Looker 專案設定中取得 Webhook 部署密鑰，向 Git 供應商驗證專案的 Git 整合。詳情請參閱「設定 Webhook 部署密鑰」說明文件頁面。

取得 Webhook 網址和部署 Webhook 密碼後，即可在 Git 供應商的介面中輸入。如果 Git 提供者是 GitHub，請按照下列步驟操作：

  1. 前往 GitHub 存放區的專案存放區設定。
  2. 在存放區設定中，按一下「Webhook」。按一下「新增 Webhook」，開啟「新增 Webhook」視窗。
  3. 在「Payload URL」欄位中，貼上您從 Looker 的「Git Integration」部分複製的 Webhook 資訊。
  4. 您也可以選擇新增 Webhook 部署密鑰，向 Git 供應商驗證專案的 Git 整合。從 LookML 專案的專案設定複製部署密鑰，然後將密鑰貼到 Git 供應商介面的「Secret」欄位。詳情請參閱「設定 Webhook 部署密鑰」說明文件頁面。
  5. 在「Which events would you like to trigger this webhook?」(您想透過哪些事件觸發這個 Webhook？) 欄位中，選取「Just the push event」(僅推送事件) 選項。
  6. 按一下 [Add Webhook]。

使用部署 Webhook 從遠端 Git 存放區提取內容

如果 LookML 專案已啟用提取要求，且部署 Webhook 並非自動執行，您有時可能會發現 Looker 生產模式中顯示的 LookML，與 Git 存放區主要分支中的 LookML 不符。這可能發生於下列情況：

  • 存放區啟用提取要求時
  • 如果 LookML 是在 Looker 開發環境以外編輯，例如：
    • 在 Git 存放區本身
    • 在其他 Looker 執行個體上，例如測試執行個體

您可以使用部署 Webhook，將 Looker 生產環境分支版本同步至存放區的主要分支版本：

  1. 開啟新的瀏覽器分頁，然後輸入下列網址，並將 <instance_url> 替換為 Looker 執行個體網址，<project_name> 則替換為 LookML 專案名稱：

    <instance_url>/webhooks/projects/<project name>/deploy

  2. 執行部署 Webhook 網址後，空白網頁會顯示類似以下的成功訊息：

    {"operations":[{"error":false,"error_code":0,"command":"Checkout Branch #\u003cLooker::GitBranch:0x5798672b\u003e","node_id":728,"results":["Success"]},{"error":false,"error_code":0,"command":"jgit revert_repo","node_id":728,"results":["Success"]}],"new_head":"05f772af48709fc2799fefe408e3fdd895a63284","old_head":"77412cad9fd7ed3eed1627afa201fdf7dcb97dd1"}

現在，Looker 的實際工作環境模式已更新，可反映遠端 Git 主要分支。您的個人開發人員分支和共用分支不會受到影響。

從遠端 Git 存放區提取部署密鑰的 Webhook

如果 LookML 專案也需要部署 Webhook 密鑰，才能將變更從主要分支推送至正式版分支，當您使用前一節「使用部署 Webhook 從遠端 Git 存放區提取內容」所述方法，將正式版分支與存放區的主要分支同步處理時，就會收到下列其中一個錯誤訊息：

{"error":"Uh oh! Something went wrong."}

或：

{"error":"Not found."}

您可以在終端機中執行下列 curl 指令，並提供 Webhook 密鑰，不必使用部署 Webhook。請務必替換下列欄位：

  • 將 <instance_URL> 替換為您的 Looker 執行個體網址。
  • 將 <deploy_secret> 替換為專案的部署密鑰。
  • 將 <project_name> 替換為 LookML 專案名稱。
curl -i -X POST -H "X-Looker-Deploy-Secret:<deploy_secret>" https://<instance_url>/webhooks/projects/<project_name>/deploy

舉例來說，如果要在 Brettcase 執行個體上，將 ecommerce_project 的正式版分支與存放區的主要分支同步處理：

curl -i -X POST -H "X-Looker-Deploy-Secret:123123123secretgoeshere123123123" https://brettcase.looker.com/webhooks/projects/ecommerce_project/deploy

Git 供應商介面中的合併選項

如果 Looker 專案整合了提取要求，開發人員可以使用 Git 供應商的介面提交提取要求，並將變更合併至正式環境分支版本。

Looker 支援合併提交方法，可將開發分支版本的變更合併至正式版分支版本。不過，Git 供應商的介面可能會顯示其他合併選項，例如「Squash and merge」或「Rebase and merge」。

Looker 不支援合併壓縮或合併重定基準，因此開發人員應避免使用這些選項。如果可以，最佳做法是為存放區停用這些選項。如要在 GitHub 存放區中停用這些選項，請按照下列步驟操作：

  1. 前往「Settings」分頁，存取 GitHub 上的專案存放區設定。

    提示：如果專案已設定 Git 整合功能，您可以透過 Looker 中專案的 Git 選單，使用「在 Git 上查看專案」選項。

  2. 在存放區設定中，按一下導覽選單中的「選項」。

  3. 前往「合併按鈕」部分，只勾選「允許合併提交」選項。停用「允許合併壓縮」和「允許合併變基」選項。

停用合併選項後，開發人員在存放區中合併分支版本時，GitHub 就不會顯示這些選項。