連結至第三方 Git 存放區

本文說明如何將遠端存放區連結至 Dataform 存放區。連結存放區後，您在 Dataform 開發工作區中所做的變更，就能推送至遠端 Git 存放區，或從該處提取。

重要事項： Dataform 無法直接連線至地端 Git 主機的私人 IP 位址。

您可以透過 HTTPS 或 SSH 連線至遠端存放區。

下表列出支援的 Git 供應商，以及其存放區可用的連線方法：

Git 供應商	連線方法
Azure DevOps Services	SSH
Bitbucket	SSH
GitHub	SSH 或 HTTPS
GitLab	SSH 或 HTTPS

重要事項： 如要將遠端 Git 存放區連線至 Dataform，請確認 Git 主機具有公開 IP 位址。如果 Git 主機只設定私人 IP 位址 (例如 10.x.x.x、172.16.x.x-172.31.x.x 或 192.168.x.x)，Dataform 就無法建立連線。如果遠端存放區未向公開網路開放 (例如位於防火牆後方)，將遠端 Git 存放區連線至 Dataform 存放區可能會失敗。在這種情況下，請將必要的 Dataform 輸出 IP 位址範圍新增至防火牆規則，以啟用與受保護遠端存放區的連線。

事前準備

1. 如果貴機構或專案透過 dataform.restrictGitRemotes 機構政策限制遠端 Git 存放區，請先將遠端 Git 存放區新增至政策中的允許清單，再建立要連線至遠端存放區的 Dataform 存放區。詳情請參閱「限制遠端存放區」。
2. 選取或建立 Dataform 存放區。 您稍後需要這個值，才能與預設的 Dataform 服務代理共用密鑰。

必要的角色

如要取得將 Dataform 存放區連結至遠端 Git 存放區所需的權限，請要求管理員授予存放區的 Dataform 管理員 (roles/dataform.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

透過 SSH 連線至遠端存放區

如要透過 SSH 連線至遠端存放區，您需要產生 SSH 金鑰和 Secret Manager 密鑰。安全殼層金鑰包含公開安全殼層金鑰和私密安全殼層金鑰。您必須將公開安全殼層金鑰提供給 Git 供應商，並使用私密安全殼層金鑰建立 Secret Manager 密鑰。然後與預設的 Dataform 服務代理共用密鑰。

Dataform 會使用含有私密安全殼層金鑰的 Secret 登入 Git 供應商，代表開發人員提交變更。Dataform 會使用開發人員的 Google Cloud 電子郵件地址進行這些提交，因此您可以判斷每個提交是由誰所為。

警告： 所有使用對應服務代理程式或服務帳戶的 Dataform 使用者，都會共用私密 SSH 金鑰。建議您使用 Git 供應商建立電腦使用者，並限制該使用者存取您打算搭配 Dataform 使用的遠端 Git 存放區。只有 Google Cloud 專案擁有者和具備「Dataform 管理員」角色的 Dataform 使用者，才能使用金鑰連結存放區。Dataform 使用者無法查看金鑰本身。

如要透過 SSH 將遠端存放區連結至 Dataform 存放區，請按照下列步驟操作：

1. 在 Git 供應商中執行下列操作：

   Azure DevOps Services

   1. 在 Azure DevOps Services 中建立私密安全殼層金鑰。
   2. 將公開安全殼層金鑰上傳至 Azure DevOps Services 存放區。

   Bitbucket

   1. 在 Bitbucket 中建立私密 SSH 金鑰。
   2. 將公開安全殼層金鑰上傳至 Bitbucket 存放區。

   GitHub

   1. 在 GitHub 中建立私密安全殼層金鑰。
   2. 將 GitHub 公開安全殼層金鑰上傳至 GitHub 存放區。

   GitLab

   1. 在 GitLab 中建立私密 SSH 金鑰。
   2. 將 GitLab 公開 SSH 金鑰上傳至 GitLab 存放區。

2. 在 Secret Manager 中建立密鑰，並將私人安全殼層金鑰設為密鑰值。

   1. 授予預設 Dataform 服務代理人密鑰存取權。

      預設 Dataform 服務代理程式的格式如下：

      [e-mail]
      

   2. 將 roles/secretmanager.secretAccessor 角色指派給服務代理人或服務帳戶。

3. 前往 Google Cloud 控制台的「Dataform」頁面。

   前往 Dataform

4. 選取要連結至遠端存放區的 Dataform 存放區。

5. 在存放區頁面中，按一下「設定」>「Connect with Git」。

6. 在「Link to remote repository」(連結至遠端存放區) 窗格的「Remote Git repository URL」(遠端 Git 存放區網址) 欄位中，輸入遠端 Git 存放區的網址，結尾為 .git。

   遠端 Git 存放區網址必須採用下列其中一種格式：

   • 絕對網址：ssh://git@{host_name}[:{port}]/{repository_path}，port 為選填。
   • 類似 SCP 的網址：git@{host_name}:{repository_path}。

7. 在「Default remote branch name」(預設遠端分支版本名稱) 欄位中，輸入遠端 Git 存放區主要開發分支版本的名稱。

8. 在「Secret」(密鑰) 下拉式選單中，選取遠端 Git 存放區的密鑰。

9. 在「SSH 公開主機金鑰值」欄位中，輸入 Git 供應商的公開主機金鑰。

   Azure DevOps Services

   1. 如要擷取 Azure DevOps Services 公開主機金鑰，請在終端機中執行下列指令：

      ssh-keyscan -t rsa ssh.dev.azure.com
      

   2. 複製其中一個輸出金鑰，並省略行首的 ssh.dev.azure.com。 複製的值必須採用下列格式：

      ALGORITHM BASE64_KEY_VALUE
      

      例如：

      ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7Hr1oTWqNqOlzGJOfGJ4NakVyIzf1rXYd4d7wo6jBlkLvCA4odBlL0mDUyZ0/QUfTTqeu+tm22gOsv+VrVTMk6vwRU75gY/y9ut5Mb3bR5BV58dKXyq9A9UeB5Cakehn5Zgm6x1mKoVyf+FFn26iYqXJRgzIZZcZ5V6hrE0Qg39kZm4az48o0AUbf6Sp4SLdvnuMa2sVNwHBboS7EJkm57XQPVU3/QpyNLHbWDdzwtrlS+ez30S3AdYhLKEOxAG8weOnyrtLJAUen9mTkol8oII1edf7mWWbWVf0nBmly21+nZcmCTISQBtdcyPaEno7fFQMDD26/s0lfKob4Kw8H
      

      確認這個金鑰仍與 Azure DevOps Services 保持最新狀態。

   Bitbucket

   1. 如要擷取 Bitbucket 公開主機金鑰，請在終端機中執行下列指令：

      curl https://bitbucket.org/site/ssh
      

   2. 這個指令會傳回公開主機金鑰清單。從清單中選擇其中一個金鑰，然後複製該金鑰，並省略行首的 bitbucket.org。 複製的值必須採用下列格式：

      ALGORITHM BASE64_KEY_VALUE
      

      例如：

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIazEu89wgQZ4bqs3d63QSMzYVa0MuJ2e2gKTKqu+UUO
      

      確認這個金鑰仍與 Bitbucket 同步。

   GitHub

   1. 如要擷取 GitHub 公開主機金鑰，請參閱 GitHub 的 SSH 金鑰指紋。

   2. 這個頁面會列出公開主機金鑰。選擇其中一個，然後複製，並省略行首的 github.com。 複製的值必須採用下列格式：

      ALGORITHM BASE64_KEY_VALUE
      

      例如：

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
      

      確認這個金鑰仍與 GitHub 同步。

   GitLab

   1. 如要擷取 GitLab 公開主機金鑰，請參閱「SSH known_hosts 項目」。

   2. 這個頁面會列出公開主機金鑰。選擇其中一個，然後複製，並省略行首的 gitlab.com。 複製的值必須採用下列格式：

      ALGORITHM BASE64_KEY_VALUE
      

      例如：

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
      

      確認這個金鑰仍與 GitLab 同步。

10. 按一下「Link」(連結)。

透過 HTTPS 連線至遠端存放區

如要透過 HTTPS 連線至遠端存放區，您需要使用個人存取權杖建立 Secret Manager 密鑰，並與預設的 Dataform 服務代理程式共用該密鑰。

接著，Dataform 會使用存取權杖登入 Git 供應商，代表開發人員提交變更。Dataform 會使用開發人員的 Google Cloud 電子郵件地址進行這些提交，因此您可以判斷每個提交是由誰完成。

警告： 所有使用對應服務代理程式或服務帳戶的 Dataform 使用者，都會共用存取權杖。建議您使用 Git 供應商建立電腦使用者，並限制該使用者存取您打算搭配 Dataform 使用的遠端 Git 存放區。只有 Google Cloud 專案擁有者和具備「Dataform 管理員」角色的 Dataform 使用者，才能使用權杖連結存放區。Dataform 使用者無法查看權杖本身。

如要透過 HTTPS 將遠端存放區連結至 Dataform 存放區，請按照下列步驟操作：

1. 在 Git 供應商中執行下列操作：

   GitHub

   1. 在 GitHub 中，建立精細的個人存取權杖或傳統的個人存取權杖。

      • 如要取得精細的 GitHub 個人存取權杖，請按照下列步驟操作：

      1. 選取存放區存取權，僅限所選存放區，然後選取要連結的存放區。

      2. 授予存放區內容的讀寫權限。

      3. 視需求設定合適的權杖到期時間。

      • 如要取得傳統 GitHub 個人存取權杖，請按照下列步驟操作：

      1. 授予 Dataform repo 權限。

      2. 視需求設定合適的權杖到期時間。

   2. 如果貴機構使用 SAML 單一登入 (SSO)，請授權權杖。

   GitLab

   1. 在 GitLab 中建立 GitLab 個人存取權杖。

   2. 將權杖命名為 dataform。

      GitLab 個人存取權杖必須命名為 dataform。

   3. 授予 Dataform api、read_repository 和 write_repository 權限。

   4. 視需求設定合適的權杖到期時間。

2. 在 Secret Manager 中，建立密鑰，其中包含遠端存放區的個人存取權杖。

3. 授予預設 Dataform 服務代理人密鑰存取權。

   預設 Dataform 服務代理程式的格式如下：

   [e-mail]
   

   1. 將 roles/secretmanager.secretAccessor 角色指派給服務代理。

4. 前往 Google Cloud 控制台的「Dataform」頁面。

   前往 Dataform

5. 選取要連結至遠端存放區的 Dataform 存放區。

6. 在存放區頁面中，按一下「設定」>「Connect with Git」。

7. 在「Link to remote repository」(連結至遠端存放區) 窗格的「Remote Git repository URL」(遠端 Git 存放區網址) 欄位中，輸入遠端 Git 存放區的網址，結尾為 .git。

   遠端 Git 存放區的網址不得包含使用者名稱或密碼。

8. 在「Default remote branch name」(預設遠端分支版本名稱) 欄位中，輸入遠端 Git 存放區主要開發分支版本的名稱。

9. 在「Secret」(密鑰) 下拉式選單中，選取遠端 Git 存放區的密鑰。

10. 按一下「Link」(連結)。

編輯遠端存放區連線

如要編輯 Dataform 存放區與遠端 Git 存放區之間的連線，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Dataform」頁面。

   前往 Dataform

2. 按一下要編輯的存放區。

3. 在存放區頁面中，按一下「設定」>「編輯 Git 連線」。

4. 在「Link to remote repository」(連結至遠端存放區) 窗格中，編輯連線設定。

5. 按一下「Update」。

後續步驟

• 如要進一步瞭解 Dataform 存放區，請參閱「建立存放區」。

• 如要建立開發工作區，請參閱「建立工作區」。

• 如要瞭解如何排解遠端存放區連線問題，請參閱「排解 Dataform 問題」。