連結至第三方 Git 存放區

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

重要事項： Dataform 無法直接連線至地端部署 Git 主機的私人 IP 位址。如要連線至私人網路中的存放區，請使用 Developer Connect。

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

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

Git 供應商	連線方法
Azure DevOps Services	SSH
Bitbucket	Developer Connect (建議)、SSH
GitHub	Developer Connect (建議)、SSH 或 HTTPS
GitLab	Developer Connect (建議)、SSH 或 HTTPS

重要事項： 如要使用 HTTPS 或 SSH 將遠端 Git 存放區連線至 Dataform，請確認 Git 主機具有公用 IP 位址。如果 Git 主機僅設定私人 IP 位址 (例如 10.x.x.x、172.16.x.x-172.31.x.x 或 192.168.x.x)，或位於防火牆後方，建議您使用 Developer Connect 連線。如果您選擇使用 HTTPS 或 SSH 連線至受保護的遠端存放區，且該存放區具有公開 IP 位址，則必須將必要的 Dataform 輸出 IP 位址範圍新增至防火牆規則，才能啟用連線。

事前準備

1. 如果貴機構或專案透過 dataform.restrictGitRemotes 組織政策限制遠端 Git 存放區，請務必先將遠端 Git 存放區加入政策的許可清單，再建立要連線至遠端存放區的 Dataform 存放區。詳情請參閱「限制遠端存放區」。

2. 選取或建立 Dataform 存放區。您稍後需要存放區，才能與預設的 Dataform 服務代理共用密鑰。

   注意： Dataform 存放區清單只會列出為開發 Dataform 工作流程建立的存放區。BigQuery Studio 資產 (例如筆記本或已儲存的查詢) 的存放區是分開管理，不會顯示在這個清單中。

3. 請確認您在 Git 供應商中具備必要權限，且 Dataform 存放區位於支援的區域。

4. 啟用 Developer Connect API。

5. 如果將 Developer Connect 連線至 Bitbucket 存放區，請確認授權者存取權權杖具有存放區的寫入權限，Dataform 才能推送變更。詳情請參閱「建立存取權杖」。

必要的角色

如要取得將 Dataform 存放區連線至遠端 Git 存放區所需的權限，請要求系統管理員授予您存放區的下列 IAM 角色：

• Dataform 管理員 (roles/dataform.admin)
• Developer Connect 管理員 (roles/developerconnect.admin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

如要使用 Developer Connect 連結遠端存放區，請將「Developer Connect 權杖存取者」(roles/developerconnect.tokenAccessor) 和「Developer Connect Git Proxy 使用者」(roles/developerconnect.gitProxyUser) 角色授予預設的 Dataform 服務代理。預設 Dataform 服務代理程式 ID 的格式如下：

[e-mail]

使用 Developer Connect 連結遠端存放區

Developer Connect 提供導覽式介面，可簡化外部 Git 供應商與 Dataform 存放區的整合作業，不必手動管理密鑰。

使用 Developer Connect，您就能連線至私人主機網路 (例如地端部署環境或虛擬私有雲 (VPC)) 中的遠端存放區，不必將這些存放區公開至網際網路。

重要事項： 如要連線至私人網路中的 Git 存放區，必須使用 Developer Connect Proxy。在Google Cloud 控制台中建立新連線時，系統會預設啟用 Proxy。如要連線至可公開存取的 Git 存放區，系統預設會啟用 Proxy，但您可以選擇停用。如果您使用以 gcloud CLI 或 Developer Connect API 建立的現有連線，請確認已啟用 Proxy，以便存取私人網路中的存放區。

注意： 如果 Dataform 存放區和 Developer Connect 連線位於不同區域，啟用 Developer Connect Proxy 時，可能會產生額外的跨區域資料移轉費用。詳情請參閱「Developer Connect 定價」。

準備私人網路連線

如要連線至私有網路中的遠端存放區，請務必在開始設定前備妥下列資訊和資源：

• 指向內部 Git 主機的服務目錄服務的命名空間和服務名稱。
• 如果主機使用私人或自行簽署的憑證授權單位，請提供 PEM 格式的憑證授權單位憑證 (大小上限為 10 KB)。
• 驗證 Git 主機的 SSL 憑證是否包含與主機 URI 相符的主體替代名稱 (SAN)。

如要進一步瞭解如何為私有主機代管網路設定連線，請參閱下列文章：

• 設定及使用 Developer Connect Proxy
• 在私人網路中連線至 GitHub Enterprise
• 連線至私有網路中的 GitLab Enterprise 存放區
• 連線至私有網路中託管的 Bitbucket 資料中心存放區

建立新的 Developer Connect 連線

如要將遠端存放區連結至新的 Developer Connect 連線，請選取下列任一選項：

Bitbucket

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

   前往 Dataform

2. 選取存放區。

3. 前往「設定」，然後按一下「Connect with Git」(連結至 Git)。

4. 在「連結至遠端存放區」窗格的「遠端 Git 存放區通訊協定」部分，選取「Developer Connect」。

5. 在存放區選取選單中，按一下「連結新的存放區」。

6. 在「透過 Developer Connect 連結 Git 存放區」窗格中，選取「建立新連結」。

7. 選取「Bitbucket」做為供應商。

8. 指定連線區域和連線名稱。

9. 提供工作區名稱、授權者存取權杖和讀取存取權杖。

10. 按一下「繼續」，然後選取要連結的遠端存放區，並按一下「連結」。

11. 在 Dataform 中，選取遠端存放區和預設分支。

12. 按一下「連結」即可完成設定。

GitHub

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

   前往 Dataform

2. 選取存放區。

3. 前往「設定」，然後按一下「Connect with Git」(連結至 Git)。

4. 在「連結至遠端存放區」窗格的「遠端 Git 存放區通訊協定」部分，選取「Developer Connect」。

5. 在存放區選取選單中，按一下「連結新的存放區」。

6. 在「透過 Developer Connect 連結 Git 存放區」窗格中，選取「建立新連結」。

7. 選取「GitHub」GitHub做為供應商。

8. 指定連線區域和連線名稱。

9. 如要觸發 OAuth 驗證流程，請按一下「繼續」，然後執行下列操作：

   1. 按一下「我瞭解並繼續」。
   2. 選取「將 GitHub 應用程式安裝至其他 GitHub 帳戶」，然後按照提示授權存取 GitHub 帳戶和特定存放區。
   3. 選取要安裝 Dataform GitHub 應用程式的帳戶。
   4. 在「存放區存取權」部分，選取要授予所有存放區的存取權，還是只授予部分存放區的存取權。
   5. 按一下 [儲存]。

10. 選取要連結的遠端存放區，然後按一下「連結」。

11. 在 Dataform 中，選取遠端存放區和預設分支。

12. 按一下「連結」即可完成設定。

GitLab

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

   前往 Dataform

2. 選取存放區。

3. 前往「設定」，然後按一下「Connect with Git」(連結至 Git)。

4. 在「連結至遠端存放區」窗格的「遠端 Git 存放區通訊協定」部分，選取「Developer Connect」。

5. 在存放區選取選單中，按一下「連結新的存放區」。

6. 在「透過 Developer Connect 連結 Git 存放區」窗格中，選取「建立新連結」。

7. 選取「GitLab」GitLab做為供應商。

8. 指定連線區域和連線名稱。

9. 提供 API 存取權杖和讀取 API 存取權杖。如要瞭解如何執行這項操作，請參閱「建立存取權杖」。

10. 按一下「繼續」，然後選取要連結的遠端存放區，並按一下「連結」。

11. 在 Dataform 中，選取遠端存放區和預設分支。

12. 按一下「連結」即可完成設定。

使用現有的 Developer Connect 連線

如要將遠端存放區連結至現有的 Developer Connect 連線，請按照下列步驟操作：

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

   前往 Dataform

2. 選取存放區。

3. 前往「設定」，然後按一下「Connect with Git」(連結至 Git)。

4. 在「連結至遠端存放區」窗格的「遠端 Git 存放區通訊協定」部分，選取「Developer Connect」。

5. 在存放區選取選單中，選取屬於現有 Developer Connect 連線的存放區。

6. 在 Dataform 中，選取遠端存放區和預設分支。

7. 按一下「連結」即可完成設定。

透過 SSH 連線至遠端存放區

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

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

警告： 所有對自訂服務帳戶具有act-as 權限的 Dataform 使用者，都會共用私密 SSH 金鑰。建議您使用 Git 供應商建立電腦使用者，並限制該使用者存取您打算與 Dataform 搭配使用的遠端 Git 存放區。只有 Google Cloud 專案擁有者和具備 Dataform 管理員角色 (roles/dataform.admin) 的 Dataform 使用者，才能使用 SSH 金鑰連線至存放區。Dataform 使用者無法查看 SSH 金鑰本身。

如要透過 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. 在「連結至遠端存放區」窗格的「遠端 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 管理員角色 (roles/dataform.admin) 的 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. 在「連結至遠端存放區」窗格的「遠端 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 問題」。