連結至 GitHub

本頁面說明如何建立與 GitHub 的連線,以及建立 GitHub 存放區的連結。您可以使用 Google Cloud 控制台或 Google Cloud CLI 完成這些工作。

以下操作說明適用於想搭配 Google 使用 GitHub 原始碼存放區的應用程式開發人員、平台管理員和安全性管理員。

舉例來說,您可以根據程式碼集,從 Gemini Code Assist 取得程式設計建議,也可以使用連結的 GitHub 存放區,透過 Firebase App Hosting 開發網頁應用程式。

如要進一步瞭解 Developer Connect,請參閱「Developer Connect 總覽」。

事前準備

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Developer Connect, Secret Manager APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  4. 確認您有權存取 GitHub 帳戶。

    為確保團隊工作安全,建議您使用機器人帳戶或團隊共用帳戶 (而非個人帳戶) 完成本指南中的工作。

  5. 確認您擁有 GitHub 存放區,或具備共用存放區的管理員層級權限。
  6. 選用:建立客戶自行管理的加密金鑰 (CMEK),用於加密 Developer Connect 建立的驗證密鑰。
  7. 選用:如要使用本指南中的指令列操作說明,請完成下列步驟:
    1. 安裝 Google Cloud CLI。如果您先前已安裝 gcloud CLI,請務必執行 gcloud components update,確認您使用的是最新版本。
    2. 執行下列指令,建立 Developer Connect 服務帳戶,其中 PROJECT_ID 是您的Google Cloud 專案 ID:
              gcloud beta services identity create \
                  --service=developerconnect.googleapis.com \
                  --project=PROJECT_ID
              

必要的角色

如要取得建立連線和連結所需的權限,請要求管理員授予您下列 IAM 角色:

  • 如果您不是專案擁有者: 使用者帳戶具備 Developer Connect 管理員 (roles/developerconnect.admin) 角色。
  • 如要使用 CMEK 加密 Developer Connect 建立的密鑰: Secret Manager 服務帳戶的 Cloud KMS CryptoKey 加密者/解密者 (roles/cloudkms.cryptoKeyEncrypterDecrypter)。
  • 如要使用 gcloud CLI 完成本指南中的步驟:Developer Connect 服務帳戶的 Secret Manager 管理員角色 (roles/secretmanager.admin)。
  • 如果您打算使用 Google Cloud 控制台完成本指南中的步驟:使用者帳戶須具備專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) 角色。

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

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

建立連線

本節說明如何在 Developer Connect 和 GitHub 之間建立連線。如果您使用 Google Cloud 控制台,也可以在完成連線設定後,開始新增存放區連結。

如要建立新的 GitHub 連線,請選取下列其中一個選項:

控制台

請按照下列步驟建立連結:

  1. 在 Google Cloud 控制台開啟「Developer Connect」。

    前往 Developer Connect

    Developer Connect 會顯示「Git repositories」(Git 存放區) 頁面。

    • 如果看到原始碼管理服務供應商清單:請選取原始碼管理服務供應商,開始設定第一個連線。按一下 GitHub 資訊卡上的「Connect」(連結)。
    • 如果看到列出現有連線的表格:請依序點選「Create connection」(建立連線) >「GitHub」,設定原始碼管理供應商。

      「Create Connection」(建立連線) 頁面隨即開啟。

  2. 在「Region」(區域) 部分,選擇連線資源的區域。

    1. 在「Name」(名稱) 部分,輸入新連線的名稱。
  3. 勾選「Enable a data residency compliant connection」(啟用符合資料落地規定的連線) 核取方塊,讓這項連線符合資料落地規定。

    使用 Google Cloud 控制台建立 GitHub 連線時,只要勾選這個核取方塊,連線就會符合資料落地規定。這時 Developer Connect 會建立 GitHub 應用程式,

    使用 Google Cloud CLI 建立 GitHub 連線時,這些連線不符合資料落地規定。所有其他連線類型都符合資料落地規定。

  4. 按一下「顯示更多」,查看選用的配置設定。

    1. 選用:在「Encryption」(加密) 區段中,選取 CMEK 金鑰,加密 Developer Connect 建立的 Secret Manager 密鑰。

    2. 選用:根據預設,Developer Connect 可做為 Proxy,對 GitHub 執行 Git 呼叫。如要停用這個選項,請取消勾選「Enable Developer Connect proxy」(啟用 Developer Connect Proxy) 核取方塊。

  5. 按一下「繼續」。

  6. 點選「我瞭解並繼續」,同意與 Developer Connect 共用 GitHub OAuth 權杖,並將權杖儲存在 Secret Manager。

  7. 如果系統提示,請登入 GitHub。

  8. 按一下「Authorize Developer Connect」,允許 Google Developer Connect 應用程式存取您的 GitHub 帳戶。

    如果沒有看到這個提示,表示這個帳戶已獲得授權。

  9. 如果您選取「Enable a data residency compliant connection」(啟用符合資料落地規定的連線),系統會提示您建立 GitHub 應用程式。

    1. 為這個 GitHub 應用程式命名。

    2. 按一下「Create GitHub app」(建立 GitHub 應用程式)。

    3. 選取要安裝應用程式的目標 (GitHub 帳戶或組織)。

    4. 選取要安裝 GitHub 應用程式的存放區,或選取「All repositories」(所有存放區),然後按一下「Install」(安裝)。

    5. 選取要為這個連線連結的存放區,然後按一下「Ok」(確定)。

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

GitHub 會建立權杖,Developer Connect 則會將權杖以 Secret Manager 密鑰的形式儲存在Google Cloud 專案中。如要進一步瞭解如何管理密鑰,請參閱「查看密鑰詳細資料」。

如果已啟用資料落地設定,您現在會擁有 GitHub 應用程式,只要在「Connection details」(連線詳細資料) 頁面點選「Manage installation」(管理安裝作業),即可管理該應用程式。

設定連線

如果您尚未勾選「Enable data residency-compliant connection」(啟用符合資料落地規定的連線) 核取方塊,請按照下列步驟操作。

請按照下列操作說明,授予 GitHub 帳戶權限並連結至存放區。網路瀏覽器顯示的提示,取決於 GitHub 帳戶是否已安裝 Developer Connect GitHub 應用程式。

在「Developer Connect」對話方塊中,完成下列步驟:

如果看到 GitHub 帳戶清單,請完成下列步驟,安裝應用程式並連結存放區:

  1. 選擇要使用的 GitHub 帳戶。

  2. 選取一或多個要授予存取權的存放區。

如果系統提示您重複使用現有的應用程式安裝項目,請完成下列步驟,選擇要設定應用程式的位置:

  1. 按一下「GitHub Account」(GitHub 帳戶),查看已安裝 Google Developer Connect 應用程式的帳戶。如果看到要使用的帳戶,請按一下「確認」選取。

  2. 如果找不到要使用的帳戶,請按照下列步驟操作:

    1. 選擇「Install the GitHub App on another GitHub account」(將 GitHub 應用程式安裝至其他 GitHub 帳戶),然後按一下「Confirm」(確認)。

    2. 按照 GitHub 步驟允許安裝應用程式。

    3. 選取一或多個要授予存取權的存放區。

對話方塊關閉後,應用程式安裝程序即完成。

建立連線後,系統會顯示「Link repositories」(連結存放區) 頁面。

請按照下列步驟,將存放區連結至連線:

  1. 在可用存放區清單中,選取要使用的存放區。

  2. 按一下 [確定]。

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

連線會新增至「Connections」(連線) 頁面,存放區連結則會新增至 Google Cloud 控制台的「Repositories」(存放區) 頁面。您隨時可以在現有連結中新增更多連結。

如要設定 Gemini Code Assist,請按照「設定及使用 Gemini Code Assist 自訂程式碼」中的步驟繼續操作。

gcloud

下列工作需要在網路瀏覽器中執行一些操作。

請按照下列步驟建立連結:

  1. 執行 gcloud developer-connect connections create 指令,建立與 GitHub 的連線:

    gcloud developer-connect connections create CONNECTION_NAME \
        --location=REGION \
        --github-config-app=APP_TYPE \
        --git-proxy-config-enabled
    

    更改下列內容:

    • CONNECTION_NAME:連線名稱。
    • REGION:連線的區域。
    • APP_TYPE:要在 GitHub 中安裝的應用程式類型。可以是下列其中一項:

      FIREBASE,用於 Firebase App Hosting

      DATAFORM,用於 Dataform

      GEMINI_CODE_ASSIST,可與 Gemini Code Assist 搭配使用

      DEVELOPER_CONNECT:用於其他所有項目

    • --git-proxy-config-enabled:選用旗標,可讓 Developer Connect 做為 Proxy,對 GitHub 執行 Git 呼叫。

    系統會建立連線名稱。

  2. 安裝 Developer Connect GitHub 應用程式,完成連線建立作業。執行下列指令,取得應用程式安裝作業的 URI:

    gcloud developer-connect connections describe CONNECTION_NAME \
        --location=REGION
    

    更改下列內容:

    • CONNECTION_NAME:連線名稱。
    • REGION:連線的區域。

    Developer Connect 會傳回連結,以便在瀏覽器視窗中完成後續步驟。複製這個連結。

  3. 在網路瀏覽器中開啟連結。

  4. 點選「我瞭解並繼續」,同意與 Developer Connect 共用 GitHub OAuth 權杖,並將權杖儲存在 Secret Manager。

  5. 如果系統提示,請登入 GitHub。

  6. 按一下「Authorize Developer Connect」,允許 Google Developer Connect 應用程式存取您的 GitHub 帳戶。

    如果沒有看到這個提示,表示這個帳戶已獲得授權。

GitHub 會建立權杖,Developer Connect 則會將權杖以 Secret Manager 密鑰的形式儲存在Google Cloud 專案中。如要進一步瞭解如何管理密鑰,請參閱「查看密鑰詳細資料」。

如果您啟用符合資料落地規定的連線,現在會擁有 GitHub 應用程式,只要在「Connection details」(連線詳細資料) 頁面點選「Manage installation」(管理安裝作業),即可管理該應用程式。

設定連線

請按照下列操作說明,授予 GitHub 帳戶權限並連結至存放區。網路瀏覽器顯示的提示,取決於 GitHub 帳戶是否已安裝 Developer Connect GitHub 應用程式。

在「Developer Connect」對話方塊中,完成下列步驟:

如果看到 GitHub 帳戶清單,請完成下列步驟,安裝應用程式並連結存放區:

  1. 選擇要使用的 GitHub 帳戶。

  2. 選取一或多個要授予存取權的存放區。

如果系統提示您重複使用現有的應用程式安裝項目,請完成下列步驟,選擇要設定應用程式的位置:

  1. 按一下「GitHub Account」(GitHub 帳戶),查看已安裝 Google Developer Connect 應用程式的帳戶。如果看到要使用的帳戶,請按一下「確認」選取。

  2. 如果找不到要使用的帳戶,請按照下列步驟操作:

    1. 選擇「Install the GitHub App on another GitHub account」(將 GitHub 應用程式安裝至其他 GitHub 帳戶),然後按一下「Confirm」(確認)。

    2. 按照 GitHub 步驟允許安裝應用程式。

    3. 選取一或多個要授予存取權的存放區。

對話方塊關閉後,應用程式安裝程序即完成。

驗證連線

執行下列指令,確認 GitHub 連線已建立:

gcloud developer-connect connections describe CONNECTION_NAME \
    --location=REGION

更改下列內容:

  • CONNECTION_NAME:連線名稱。
  • REGION:連線所在的區域。

Developer Connect 會在 installationState 欄位中傳回狀態。如果這個欄位的值為 COMPLETE,表示應用程式安裝完成。否則,Developer Connect 會傳回 URI,將您導回瀏覽器中的設定。

連線完成後,請按照「將存放區連結新增至現有連線」中的操作說明,選擇要連結的存放區。

建立與 GitHub 的連線後,即可連結至存放區。您可以視需要重複這些步驟,連結其他存放區。

如要在現有的 GitHub 連線上建立存放區連結,請選取下列其中一個選項:

控制台

  1. 在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

    開啟「Repositories」(存放區) 頁面

  2. 按一下「連結存放區」。

    「Link Git repositories」(連結 Git 存放區) 窗格隨即開啟。

  3. 在連線清單中選擇連線。

  4. 按一下「繼續」。

  5. 在存放區清單中,選取要連結的存放區。

  6. 點選「建立」。

Developer Connect 會建立存放區連結,並顯示在 Google Cloud 控制台中。

gcloud

執行下列指令:

gcloud developer-connect connections git-repository-links create REPO_NAME \
    --clone-uri=REPO_URI \
    --connection=CONNECTION_NAME \
    --location=REGION

更改下列內容:

  • REPO_NAME:存放區名稱。
  • REPO_URI:GitHub 存放區連結。例如:https://github.com/cloud-build/test-repo.git。
  • CONNECTION_NAME:連線名稱。
  • REGION:連線的區域。

Developer Connect 會建立存放區連結。

如要列出連結的存放區,請執行 developer-connect connections git-repository-links list 指令。

如要設定 Gemini Code Assist,請按照「設定及使用 Gemini Code Assist 自訂程式碼」中的步驟繼續操作。

資料共用

連結至這個連線的 Google Cloud 資源內容可能會移轉至 GitHub。這項聲明適用於使用這個連線的所有資源,包括現有和日後建立的資源。如要停止與 GitHub 共用資訊,請在 Google Cloud 控制台或 gcloud CLI 中刪除 Developer Connect 連線,並在 GitHub 中撤銷存取權。

後續步驟