疑難排解

本頁面說明如何解決 Secure Source Manager 的問題。

建立存放區時出現錯誤訊息

嘗試建立存放區時，系統會顯示下列錯誤：

There was an error while loading /repo/create. Try refreshing the page.

發生這個問題的可能原因如下：

  • 專案未啟用 Secure Source Manager API。
  • 您不具備專案的存放區管理員角色，或沒有在 Secure Source Manager 執行個體中建立存放區的權限。

如何解決這個問題：

  • 在專案中啟用 Secure Source Manager API。
  • 請管理員授予您下列角色：
    • 專案的存放區管理員 (roles/securesourcemanager.repoAdmin) 角色。
    • Secure Source Manager 執行個體的執行個體存取者 (roles/securesourcemanager.instanceAccessor)。
    • Secure Source Manager 執行個體的執行個體存放區建立者 (roles/securesourcemanager.instanceRepositoryCreator)。

詳情請參閱「使用 IAM 控管存取權」。

在 Mac 上複製存放區時出現錯誤訊息

嘗試複製存放區時，系統會顯示下列錯誤：

git: 'credential-gcloud.sh' is not a git command.  See 'git --help'.
fatal: Authentication failed for [repo-url]

發生這個問題的原因如下：

  • gcloud CLI 是使用 Homebrew 或其他非標準安裝方式安裝。
  • git-credential-gcloud.sh 未新增至 PATH。

如何解決這個問題：

  • 執行 source $HOMEBREW_PREFIX/Caskroom/google-cloud-sdk/latest/google-cloud-sdk/path.zsh.inc

  • 執行下列指令，確認 git-credential-gcloud.sh 位於路徑中：

    which git-credential-gcloud.sh

SSH 連線失敗，並顯示「no matching」錯誤

嘗試透過 SSH 執行 Git 作業時，您可能會收到下列其中一則錯誤訊息：

  • Unable to negotiate with <host> port <port>: no matching key exchange method found.
  • Unable to negotiate with <host> port <port>: no matching cipher found.
  • Unable to negotiate with <host> port <port>: no matching MAC found.

如果 SSH 用戶端不支援 Secure Source Manager 所需的密碼編譯演算法，就會發生這個問題。如果您使用的是舊版 SSH 用戶端，或用戶端未設定使用支援的演算法，就可能發生這種情況。

Secure Source Manager 必須使用下列其中一種演算法：

  • 金鑰交換演算法：curve25519-sha256、diffie-hellman-group14-sha256
  • 加密：chacha20-poly1305@openssh.com、aes128-ctr、aes192-ctr、aes256-ctr、aes128-gcm@openssh.com、aes256-gcm@openssh.com
  • MAC：hmac-sha2-256-etm@openssh.com、hmac-sha2-256

如要解決這個問題，請將 SSH 用戶端更新至支援這些演算法的最新版本。

Git HTTPS 要求失敗，並顯示權限遭拒或未授權錯誤

嘗試透過 HTTPS 執行 Git 指令時，系統會顯示權限遭拒或未授權的錯誤訊息。

發生這個問題的可能原因如下：

  • 全域 Git 設定檔缺少 Secure Source Manager 驗證輔助程式。
  • 系統目前使用 Git 內建的憑證儲存庫，而非呼叫 Secure Source Manager 驗證輔助程式來取得新憑證。
  • 系統正在使用憑證輔助程式，而非呼叫 Secure Source Manager 驗證輔助程式來取得新憑證。
  • 使用 HTTPS 與 Secure Source Manager 存放區互動時，會使用舊版 Google Cloud CLI。Secure Source Manager 須使用 Google Cloud CLI 395.0.0 以上版本。

如何解決這個問題：

  1. 執行下列指令，判斷全域 Git 設定的內容。

    git config --list | grep credential

  2. 如果 macOS 上有類似 *credential*.helper=store 的行，或 Windows OS 上有類似 credential.helper = manager 的行，請移除這些行，然後使用 gcloud auth login 重新驗證，再嘗試執行 Git 指令。

  3. 如果回應不包含 macOS 或 Linux 上的 credential.https://*.*.sourcemanager.dev.helper=gcloud.sh，或 Windows 上的 credential.https://*.*.sourcemanager.dev.helper=gcloud.cmd，請將 Secure Source Manager 驗證輔助程式新增至全域 Git 設定：

    Linux

    1. 如要將 Secure Source Manager 驗證輔助程式新增至全域 Git 設定，請執行下列指令：

      git config --global credential.'https://*.*.sourcemanager.dev'.helper gcloud.sh

    2. 執行下列指令，驗證驗證輔助程式行是否已新增至全域 Git 設定：

      git config --list | grep credential

      輸出內容應包含 credential.https://*.*.sourcemanager.dev.helper=gcloud.sh。

    3. 執行 gcloud auth login 進行驗證。

    4. 執行 Git 指令來測試驗證。

    Windows

    1. 請按照「安裝 Git 和 Google Cloud CLI」的操作說明，查看 gcloud CLI 版本。

    2. 如要將 Secure Source Manager 驗證輔助程式新增至全域 Git 設定，請執行下列指令：

      git config --global credential.https://*.*.sourcemanager.dev.helper gcloud.cmd

    3. 執行下列指令，驗證驗證輔助程式行是否已新增至全域 Git 設定：

      git config --list | grep credential

      輸出內容應包含 credential.https://*.*.sourcemanager.dev.helper=gcloud.cmd。

    4. 執行 gcloud auth login 進行驗證。

    5. 執行 Git 指令來測試驗證。

  4. 如果您先前將 Git 主機的憑證設為 gcloud.sh，但收到 'credential-gcloud.sh' is not a git command 等錯誤，表示 Git 無法在機器的 PATH 中找到 git-credential-gcloud.sh 指令碼。請更新 PATH，或將 gitconfig 檔案中的 gcloud.sh 替換為絕對路徑。

Git HTTPS 要求失敗，權杖無效

必須提供有效的 OAuth 權杖，做為 Git HTTPS 作業的密碼。這項作業通常由 Git 憑證輔助程式處理，但也可以使用其他方法產生的 OAuth 權杖 (例如應用程式預設憑證)。

如果 Git 要求因權杖無效而遭拒，通常表示無法從傳入的權杖擷取使用者資訊，這項錯誤可能有多種原因：

  • gcloud CLI 登入資訊可能已過期。

    使用 gcloud auth login 重新登入。

  • 權杖範圍不足。OAuth 權杖應具備下列範圍：

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/userinfo.email

    您可以呼叫 curl https://oauth2.googleapis.com/tokeninfo?access_token=${TOKEN} 來檢查權杖範圍

  • 您使用的是 GKE 機群 Workload Identity 產生的權杖：

  • 您有組織政策，禁止在特定範圍外使用權杖，例如情境感知存取權。

    如要解決這個問題，請將 git_helper_use_adc gcloud CLI 設定屬性設為 true，並更新應用程式預設憑證 (ADC)：

    1. 使用應用程式預設憑證登入：

      gcloud auth application-default login

    2. 設定 git_helper_use_adc 屬性：

      gcloud config set auth/git_helper_use_adc true

憑證過時，導致 macOS 上的 Git HTTPS 要求失敗，並顯示 403 錯誤

在 macOS 上透過 HTTPS 執行 Git 作業時，可能會收到 403 錯誤。

如果您在 macOS 上使用 iCloud 鑰匙圈，可能會發生這個問題，因為 iCloud 鑰匙圈會儲存及同步處理過時的權杖，干擾 gcloud CLI 驗證權杖。這些過時的權杖可能會導致 Secure Source Manager 驗證失敗，即使您使用 gcloud auth login 重新驗證也一樣。

如要解決這個問題，請手動從 Keychain Access 刪除過時的憑證：

  1. 在 Mac 上開啟「Keychain Access」應用程式 (位於 /Applications/Utilities/)。
  2. 搜尋 sourcemanager.dev。
  3. 在與 *.*.sourcemanager.dev 或 Secure Source Manager 執行個體網址相符的「網際網路密碼」類型項目上按一下滑鼠右鍵，然後選取「刪除」，即可刪除該項目。
  4. 刪除項目後，請重試 Git 作業。系統可能會提示您使用 gcloud CLI 重新驗證。如果 Git 作業持續失敗，請先執行 gcloud auth login，然後再試一次。

使用 Kubernetes 服務帳戶 (KSA) 權杖和 GKE 機群 Workload Identity 時，SSM 會傳回錯誤

使用 GKE 機群 Workload Identity 時，Secure Source Manager 不支援原始 KSA 權杖。使用這些權杖會導致錯誤。

如要解決這個問題，您必須模擬服務帳戶，並將工作負載繫結至 Google 服務帳戶。您也需要在 KSA 設定中加入下列註解：

iam.gke.io/gcp-service-account: SERVICE_ACCOUNT@PROJECT_ID.

專案未顯示在網頁介面產品選取器中

使用 Secure Source Manager 網頁介面產品選取器時，專案不會顯示。

如果您有多組 Secure Source Manager 登入憑證，就會發生這個問題。

如何解決這個問題：

  • 在 Secure Source Manager 執行個體網址後方附加下列內容，即可清除 Cookie：/_oauth/consent

    舉例來說，如果執行個體網址是 https://my-instance-098765432123.us-central1.sourcemanager.dev/，請在瀏覽器網址列中輸入 https://my-instance-098765432123.us-central1.sourcemanager.dev/_oauth/consent，然後使用正確的憑證登入。

觸發條件檔案不會觸發建構作業

如果提交觸發條件檔案後，建構作業未如預期觸發，可能是下列其中一項問題：

  • 觸發條件檔案不在預設分支版本中。如要解決這個問題，請將觸發條件檔案移至預設分支版本。
  • 觸發條件檔案格式無效。存放區頁面會顯示橫幅，指出這項錯誤：Build triggers configuration error: ...。如要修正這個問題，請參閱觸發條件檔案結構定義。觸發條件檔案設定正確時，存放區頁面的橫幅會顯示「Valid build triggers configuration」。

自動建構觸發條件設定錯誤

將 triggers.yaml 檔案提交至 Secure Source Manager 存放區後，橫幅會顯示下列錯誤：

Build cannot be created.

發生這個問題的原因如下：

  • Cloud Build 建構設定檔的選項或格式無效。
  • Secure Source Manager 服務代理不具備存放區使用者自行管理服務帳戶的服務帳戶權杖建立者角色。
  • 使用者自行管理的服務帳戶，不具備 Cloud Build 服務帳戶的服務帳戶使用者角色。
  • 在執行建構作業的專案中，使用者自行管理的服務帳戶不具備 Cloud Build 編輯者角色。
  • 組織政策 iam.disableCrossProjectServiceAccountUsage 封鎖了使用者自管服務帳戶的使用 (如果服務帳戶位於其他專案)。

如何修正這個問題：

  • 請務必遵循正確的觸發條件檔案結構定義。
  • 確認已授予所有必要角色。請參閱「必要的服務帳戶角色」。
  • 如果使用其他專案中由使用者管理的服務帳戶，請確認託管服務帳戶的專案已停用組織政策 iam.disableCrossProjectServiceAccountUsage。

執行期間建構失敗

如果建構作業成功觸發，但在執行期間失敗，則相關聯的修訂版本會顯示「失敗」修訂版本狀態。

如要排解建構失敗的問題，請在存放區頁面中，按一下失敗修訂版本狀態旁的「Details」(詳細資料)。

Cloud Build 執行記錄隨即開啟。如要進一步瞭解如何排解 Cloud Build 中的建構作業問題，請參閱「排解建構錯誤」。

偵測到機密資料，因此 Git 推送遭拒

將修訂版本推送至已啟用 Secret 掃描功能的存放區時，推送作業會失敗，並顯示類似以下的錯誤訊息：

remote: Push rejected: Sensitive data detected.

如果 Secret 掃描或自訂檢查範本在修訂版本記錄中發現機密資訊，就會發生這個問題。

如何解決這個問題：

  • 使用 git reset --soft 還原問題修訂版本，並在再次修訂前移除機密資訊。

  • 如果偵測到的資訊可以接受，且您具備適當權限，請使用 -o dlpskip=true 推送選項略過檢查：

    git push -o dlpskip=true origin BRANCH_NAME

重新建立後，每日配額未重設

刪除 Secure Source Manager 執行個體後，如果在當天使用相同的執行個體 ID 重新建立，可能會收到密鑰掃描配額用盡或達到上限的錯誤訊息。

發生這個問題的原因是，Secret 掃描配額是與執行個體 ID 連結的每日頻率配額。如果您在當天刪除並重新建立具有相同 ID 的執行個體，配額用量不會重設。

如要解決這個問題，請採取下列任一做法：

  • 等到第二天，每日配額用量會自動重設為 0。
  • 使用其他不重複的執行個體 ID 重新建立執行個體。
  • 請暫時略過 Secret 掃描，或申請提高配額。詳情請參閱「提高可用配額」。

設定存放區服務帳戶時發生錯誤

嘗試使用使用者自行管理的服務帳戶建立或更新存放區時，會出現下列錯誤：

Permission denied on resource ...

如果嘗試與存放區建立關聯的服務帳戶，未具備服務帳戶使用者 (roles/iam.serviceAccountUser) 角色，就會發生這個問題。Secure Source Manager 會先驗證您是否具備以服務帳戶身分操作的權限，再允許您將服務帳戶與存放區建立關聯。

如要解決這個問題，請要求管理員授予您服務帳戶的「服務帳戶使用者」角色。