連結至第三方 Git 存放區

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

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

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

Git 供應商	連線方法
Azure DevOps Services	SSH
Bitbucket	Developer Connect (建議)、SSH
GitHub	Developer Connect (建議)、SSH 或 HTTPS
GitLab	Developer Connect (建議)、SSH 或 HTTPS
Secure Source Manager (預先發布版)	Developer Connect

事前準備

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

2. 選取或建立 Dataform 存放區。稍後您需要使用存放區，與預設 Dataform 服務代理共用 Secret。

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

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

4. 啟用 Developer Connect API。

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

6. 如要將 Developer Connect 連結至 Secure Source Manager (預先發布版) 執行個體，請確認您有可運作的 Secure Source Manager 執行個體，並在 Secure Source Manager 執行個體的專案中，將 roles/securesourcemanager.developerConnectLinker 角色授予 Developer Connect 服務代理。詳情請參閱「連結至 Secure Source Manager」。

網路連線需求和限制

將遠端 Git 存放區連結至 Dataform 前，請確認網路設定符合所選連線方式的要求。

私人網路連線

Dataform 不支援直接連線至地端部署 Git 主機或私有網路中存放區的私有 IP 位址 (例如 10.x.x.x、172.16.x.x-172.31.x.x 或 192.168.x.x)，也不支援使用 HTTPS 或 SSH 連線。包括使用虛擬私有雲 (VPC)、VPN 或 Cloud Interconnect 存取。

如要連線至私人網路中的存放區，或 Git 主機位於防火牆後方，請使用 Developer Connect 連線。

公用網路連線

如要使用 HTTPS 或 SSH 連線至遠端 Git 存放區，Git 主機必須有公開 IP 位址。

如果您使用 HTTPS 或 SSH 連線至具有公開 IP 位址的受保護遠端存放區，請務必將必要的 Dataform 輸出 IP 位址範圍新增至防火牆規則。

VPC Service Controls 規定

如果專案使用 VPC Service Controls，您必須設定 dataform.restrictGitRemotes 組織政策，才能連線至任何第三方 Git 存放區。詳情請參閱「限制遠端存放區」。

必要的角色

如要取得將 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]

重要事項： 將角色授予預設 Dataform 服務代理時，請務必只授予必要的特定預先定義角色 (例如 Developer Connect 權杖存取者和 Git Proxy 使用者)。授予權限過高的角色會造成安全風險。

使用 Developer Connect 連結遠端存放區

Developer Connect 提供引導式介面，可簡化外部 Git 供應商與 Dataform 存放區的整合程序，不必手動管理 Secret。

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

重要事項： 如要連線至私有網路中的 Git 存放區，以及 Secure Source Manager (預先發布版) 執行個體，必須使用 Developer Connect Proxy。在 Google Cloud 控制台建立新連線時，系統預設會啟用 Proxy。如果是連至可公開存取的 Git 存放區，系統預設會啟用 Proxy，但您可以選擇停用。如果是 Secure Source Manager 連線，Proxy 必須保持啟用狀態。如果停用 Proxy，Dataform 就無法存取 Secure Source Manager 存放區。如要使用透過 gcloud CLI 或 Developer Connect API 建立的現有連線，存取私人網路或 Secure Source Manager 中的存放區，請務必啟用 Proxy。

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

準備私人網路連線

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

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

如要進一步瞭解如何設定私人託管網路的連線，請參閱下列文章：

• 設定及使用 Developer Connect Proxy
• 在私人網路中連線至 GitHub Enterprise
• 連線至私人網路中的 GitLab Enterprise 存放區
• 連線至託管於私人網路的 Bitbucket Data Center 存放區
• 連線至 Secure Source Manager (預先發布版)

建立新的 Developer Connect 連線

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

Bitbucket

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

   前往 Dataform

2. 選取存放區。

3. 前往「設定」，然後點選「連結 Git」。

4. 在「Link to remote repository」(連結至遠端存放區) 窗格的「Remote Git repository protocol」(遠端 Git 存放區通訊協定) 部分，選取「Developer Connect」。

5. 在存放區選單中，點選「連結新的存放區」。

6. 在「Link Git repositories via Developer Connect」(透過 Developer Connect 連結 Git 存放區) 窗格中，選取「Create new connection」(建立新連線)。

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

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

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

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

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

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

GitHub

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

   前往 Dataform

2. 選取存放區。

3. 前往「設定」，然後點選「連結 Git」。

4. 在「Link to remote repository」(連結至遠端存放區) 窗格的「Remote Git repository protocol」(遠端 Git 存放區通訊協定) 部分，選取「Developer Connect」。

5. 在存放區選單中，點選「連結新的存放區」。

6. 在「Link Git repositories via Developer Connect」(透過 Developer Connect 連結 Git 存放區) 窗格中，選取「Create new connection」(建立新連線)。

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

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

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

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

10. 選取要連結的遠端存放區，然後點選「Link」(連結)。

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

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

GitLab

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

   前往 Dataform

2. 選取存放區。

3. 前往「設定」，然後點選「連結 Git」。

4. 在「Link to remote repository」(連結至遠端存放區) 窗格的「Remote Git repository protocol」(遠端 Git 存放區通訊協定) 部分，選取「Developer Connect」。

5. 在存放區選單中，點選「連結新的存放區」。

6. 在「Link Git repositories via Developer Connect」(透過 Developer Connect 連結 Git 存放區) 窗格中，選取「Create new connection」(建立新連線)。

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

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

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

10. 按一下「Continue」(繼續)，然後選取要連結的遠端存放區，再點選「Link」(連結)。

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

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

Secure Source Manager

預覽

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

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

   前往 Dataform

2. 選取存放區。

3. 前往「設定」，然後點選「連結 Git」。

4. 在「Link to remote repository」(連結至遠端存放區) 窗格的「Remote Git repository protocol」(遠端 Git 存放區通訊協定) 部分，選取「Developer Connect」。

5. 在存放區選單中，點選「連結新的存放區」。

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

7. 選取「Secure Source Manager」做為供應商。

8. 指定連線區域和連線名稱。連線區域必須與 Secure Source Manager 執行個體位於相同區域。

9. 在「Instance」(執行個體) 清單中，選取 Secure Source Manager 執行個體。

10. 確認已啟用 Developer Connect Proxy。 Proxy 預設會在「顯示更多」下方啟用，且 Dataform 必須使用 Proxy 才能存取 Secure Source Manager 存放區。

11. 按一下「Continue」(繼續)，然後選取要連結的遠端存放區，再點選「Link」(連結)。

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

13. 如要完成設定，請按一下「連結」。

使用現有的 Developer Connect 連線

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

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

   前往 Dataform

2. 選取存放區。

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

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

5. 在存放區選取選單中，選取透過現有 Developer Connect 連線連結的存放區。

   注意： 如果選取的存放區是透過 Secure Source Manager (預先發布版) 連線，該連線必須啟用 Developer Connect Proxy。如果連線未啟用 Proxy，Dataform 會顯示錯誤訊息，且無法存取存放區。

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

7. 如要完成設定，請按一下「連結」。

透過 SSH 連線至遠端存放區

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

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

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

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

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

   Azure DevOps Services

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

   Bitbucket

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

   GitHub

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

   GitLab

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

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

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

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

      [e-mail]
      

   2. 將 roles/secretmanager.secretAccessor 角色授予服務帳戶。

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

   前往 Dataform

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

5. 在存放區頁面，依序點選「設定」>「連線至 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 存放區的 Secret。

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 的安全殼層金鑰指紋。

   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. 將 repo 權限授予 Dataform。

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

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

   GitLab

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

   2. 將權杖命名為 dataform。

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

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

   4. 請根據需求設定適當的權杖到期時間。

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

3. 將 Secret 存取權授予預設 Dataform 服務代理。

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

   [e-mail]
   

   1. 將 roles/secretmanager.secretAccessor 角色授予服務代理。

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

   前往 Dataform

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

6. 在存放區頁面，依序點選「設定」>「連線至 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 問題」。