共用方式為

建置 Bitbucket 雲端存放庫

  • 發行項

Azure DevOps Services

Azure Pipelines 可以自動建置和驗證每個提取要求，並認可到您的 Bitbucket Cloud 存放庫。 本文說明如何設定 Bitbucket Cloud 與 Azure Pipelines 之間的整合。

Bitbucket 和 Azure Pipelines 是兩個獨立的服務，可妥善整合在一起。 您的 Bitbucket Cloud 使用者不會自動取得 Azure Pipelines 的存取權。 您必須明確地將它們新增至 Azure Pipelines。

Bitbucket 存放庫的存取權

您可以先選取 Bitbucket Cloud 存放庫，然後選取該存放庫中的 YAML 檔案，以建立新的管線。 YAML 檔案所在的存放庫稱為 self 存放庫。 根據預設，這是管線所建置的存放庫。

您稍後可以設定管線來簽出不同的存放庫或多個存放庫。 若要瞭解如何執行這項操作，請參閱 多存放庫簽出 。

Azure Pipelines 必須獲得存放庫的存取權，才能在組建期間擷取程式碼。 此外，設定管線的使用者必須具有 Bitbucket 的系統管理員存取權，因為該身分識別是用來在 Bitbucket 中註冊 Webhook。

建立管線時，有 2 種驗證類型可用來授與 Azure Pipelines 對 Bitbucket Cloud 存放庫的存取權。

驗證類型 使用 執行管線
1. OAuth 您的個人 Bitbucket 身分識別
2. 使用者名稱和密碼 您的個人 Bitbucket 身分識別

OAuth 驗證

OAuth 是開始使用 Bitbucket 帳戶中存放庫的最簡單驗證類型。 Bitbucket 狀態更新將代表您的個人 Bitbucket 身分識別執行。 若要讓管線持續運作，您的存放庫存取權必須保持作用中。

若要使用 OAuth，請在管線建立期間出現提示時登入 Bitbucket。 然後按一下 [ 授權 ] 以使用 OAuth 進行授權。 OAuth 連線將會儲存在您的 Azure DevOps 專案中以供日後使用，以及用於所建立的管線中。

注意

Azure DevOps Services 使用者介面可以載入的 Bitbucket 存放庫數目上限為 2,000。

密碼驗證

組建和 Bitbucket 狀態更新將代表您的個人身分識別執行。 若要讓組建持續運作，您的存放庫存取權必須保持作用中。

若要建立密碼連線，請造訪 Azure DevOps 專案設定中的服務連線 。 建立新的 Bitbucket 服務連線，並提供使用者名稱和密碼，以連線到您的 Bitbucket Cloud 存放庫。

CI 觸發程式

持續整合 （CI） 觸發程式會在您推送更新至指定的分支或推送指定的標記時，導致管線執行。

YAML 管線預設會在所有分支上使用 CI 觸發程式來設定，除非 已啟用 Azure DevOps 短期衝刺 227 中 引進的停用隱含 YAML CI 觸發 程式設定。 您可以在組織層級或專案層級設定停用隱含 YAML CI 觸發程式 設定。 啟用 [停用隱含 YAML CI 觸發 程式] 設定時，如果 YAML 管線沒有 trigger 區段，就不會啟用 YAML 管線的 CI 觸發程式。 預設不會啟用停用隱含 YAML CI 觸發程式 。

分支

您可以使用簡單的語法來控制哪些分支會取得 CI 觸發程式：

trigger:
- main
- releases/*

您可以指定分支的完整名稱（例如 main ）， 或萬用字元 （例如 ， releases/* 。 如需萬用字元語法的相關資訊，請參閱 萬用字元 。

注意

您無法在觸發程式中使用 變數 ，因為變數會在執行時間評估（觸發程式引發之後）。

注意

如果您使用 範本 來撰寫 YAML 檔案，則您只能在管線的主要 YAML 檔案中指定觸發程式。 您無法在範本檔案中指定觸發程式。

如需使用 exclude 或 batch 更複雜的觸發程式，您必須使用完整的語法，如下列範例所示。

# specific branch build
trigger:
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/old*

在上述範例中，如果變更推送至 main 或任何發行分支，管線將會觸發。 不過，如果對以 開頭 old 的 releases 分支進行變更，則不會觸發它。

如果您指定不含 exclude 子句的 include 子句，則它相當於在 include 子句中指定 * 。

除了在 branches 清單中指定分支名稱之外，您也可以使用下列格式，根據標記來設定觸發程式：

trigger:
  branches:
    include:
      - refs/tags/{tagname}
    exclude:
      - refs/tags/{othertagname}

如果您未指定任何觸發程式，且 未啟用 [停用隱含 YAML CI 觸發 程式] 設定，預設值會如同您撰寫的一樣：

trigger:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

重要

當您指定觸發程式時，它會取代預設的隱含觸發程式，而且只會推送至明確設定為包含的分支會觸發管線。 先處理 Include，然後從該清單中移除排除。

批次處理 CI 執行

如果您有許多小組成員經常上傳變更，您可能會想要減少您開始的執行次數。 如果您將 設定 batch 為 true ，當管線正在執行時，系統會等候執行完成，然後啟動另一個執行，並執行尚未建置的所有變更。

# specific branch build with batching
trigger:
  batch: true
  branches:
    include:
    - main

注意

batch 存放庫資源觸發程式不支援。

為了厘清此範例，讓我們假設 A main 推送會導致上述管線執行。 當該管線正在執行時，會進行額外的推送 B ，並 C 發生在存放庫中。 這些更新不會立即啟動新的獨立執行。 但在第一次執行完成之後，所有推送都會一起批次處理，並啟動新的執行。

注意

如果管線有多個作業和階段，則第一次執行仍應完成或略過其所有作業和階段，再啟動第二個執行之前，仍應達到終端狀態。 基於這個理由，您必須在具有多個階段或核准的管線中使用這項功能時小心。 如果您想要在這類情況下批次處理組建，建議您將 CI/CD 程式分割成兩個管線，一個用於建置（含批次處理），另一個用於部署。

路徑

您可以指定要包含或排除的檔案路徑。

# specific path build
trigger:
  branches:
    include:
    - main
    - releases/*
  paths:
    include:
    - docs
    exclude:
    - docs/README.md

當您指定路徑時，如果您使用 Azure DevOps Server 2019.1 或更低版本，則必須明確指定要觸發的分支。 您無法僅觸發路徑篩選的管線;您也必須有分支篩選，且符合路徑篩選準則的已變更檔案必須來自符合分支篩選的分支。 如果您使用 Azure DevOps Server 2020 或更新版本，您可以省略 branches 以篩選所有分支與路徑篩選準則。

路徑篩選支援萬用字元。 例如，您可以包含符合 src/app/**/myapp* 的所有路徑。 您可以在指定路徑篩選時，使用萬用字元 （ ** 、 * 或 ?) 。

  • 路徑一律會指定相對於存放庫根目錄。
  • 如果您未設定路徑篩選，則預設會隱含包含存放庫的根資料夾。
  • 如果您排除路徑，除非您將路徑限定為更深入的資料夾，否則也無法包含該路徑。 例如，如果您排除 /tools，則可以包含 /tools /trigger-runs-on-these
  • 路徑篩選的順序並不重要。
  • Git 中的路徑會區分大小寫 。 請務必使用與實際資料夾相同的案例。
  • 您無法在路徑中使用 變數 ，因為變數會在執行時間評估（觸發程式引發之後）。

注意

針對 Bitbucket Cloud 存放庫，使用 branches 語法是指定標記觸發程式的唯一方式。 tags:Bitbucket 不支援語法。

退出宣告 CI

停用 CI 觸發程式

您可以藉由指定 trigger: none 來完全退出 CI 觸發程式。

# A pipeline with no CI trigger
trigger: none

重要

當您將變更推送至分支時，系統會評估該分支中的 YAML 檔案，以判斷是否應該啟動 CI 執行。

略過個別認可的 CI

您也可以告訴 Azure Pipelines 略過執行管線，推送通常會觸發。 只要包含在 [skip ci] 屬於推送一部分的任何認可訊息或描述中，Azure Pipelines 就會略過此推送的執行 CI。 您也可以使用下列任何變化。

  • [skip ci] 或 [ci skip]
  • skip-checks: true 或 skip-checks:true
  • [skip azurepipelines] 或 [azurepipelines skip]
  • [skip azpipelines] 或 [azpipelines skip]
  • [skip azp] 或 [azp skip]
  • ***NO_CI***

在條件中使用觸發程式類型

根據啟動執行的觸發程式類型而定，在您的管線中執行不同的步驟、作業或階段是常見的案例。 您可以使用系統變數 Build.Reason 來執行此動作。 例如，將下列條件新增至您的步驟、作業或階段，以將其從 PR 驗證中排除。

condition: and(succeeded(), ne(variables['Build.Reason'], 'PullRequest'))

建立新分支時觸發程式的行為

設定相同存放庫的多個管線很常見。 例如，您可能有一個管線可建置應用程式的檔，而另一個管線可建置原始程式碼。 您可以在每個管線中設定具有適當分支篩選準則和路徑篩選準則的 CI 觸發程式。 例如，您可能會想要在將更新推送至資料夾時觸發一個管線，而當您將更新推送至 docs 應用程式程式碼時，可能會觸發另一個管線。 在這些情況下，您必須瞭解建立新分支時如何觸發管線。

以下是當您將新的分支（符合分支篩選準則）推送至存放庫時的行為：

  • 如果您的管線具有路徑篩選，只有在新分支變更符合該路徑篩選準則的檔案時，才會觸發它。
  • 如果您的管線沒有路徑篩選，即使新分支中沒有任何變更，也會觸發它。

萬用字元

指定分支、標記或路徑時，您可以使用確切的名稱或萬用字元。 萬用字元模式允許 * 比對零或多個字元，以及 ? 比對單一字元。

  • 如果您在 YAML 管線中使用 來啟動模式 * ，則必須以引號括住模式，例如 "*-releases" 。
  • 針對分支和標記：
    • 萬用字元可能會在模式中的任何位置出現。
  • 針對路徑：
    • 在 Azure DevOps Server 2022 和更新版本中，包括 Azure DevOps Services，萬用字元可能會在路徑模式內的任何位置出現，而且您可以使用 * 或 ? 。
    • 在 Azure DevOps Server 2020 和更低版本中，您可能會包含 * 為最後一個字元，但不會自行指定目錄名稱以外的任何動作。 您可能 未 包含在 * 路徑篩選的中間，而且可能不會使用 ? 。
trigger:
  branches:
    include:
    - main
    - releases/*
    - feature/*
    exclude:
    - releases/old*
    - feature/*-working
  paths:
    include:
    - docs/*.md

PR 觸發程式

每當提取要求以其中一個指定的目標分支開啟提取要求，或對這類提取要求進行更新時，提取要求 （PR） 觸發程式會導致管線執行。

分支

您可以在驗證提取要求時指定目標分支。 例如，若要驗證以 和 releases/* 為目標 master 的提取要求，您可以使用下列 pr 觸發程式。

pr:
- main
- releases/*

此組態會在第一次建立新的提取要求時啟動新的執行，並在每次對提取要求進行更新之後啟動。

您可以指定分支的完整名稱（例如 master ）， 或萬用字元 （例如 ， releases/* 。

注意

您無法在觸發程式中使用 變數 ，因為變數會在執行時間評估（觸發程式引發之後）。

注意

如果您使用 範本 來撰寫 YAML 檔案，則您只能在管線的主要 YAML 檔案中指定觸發程式。 您無法在範本檔案中指定觸發程式。

每個新的執行都會從提取要求的來源分支建置最新的認可。 這不同于 Azure Pipelines 建置在其他存放庫中提取要求的方式（例如 Azure Repos 或 GitHub），其會在其中建置合併認可。 不幸的是，Bitbucket 不會公開合併認可的相關資訊，其中包含提取要求的來源和目標分支之間的合併程式碼。

如果您的 YAML 檔案中未 pr 顯示任何觸發程式，則會自動為所有分支啟用提取要求驗證，就像您撰寫下列 pr 觸發程式一樣。 此組態會在建立任何提取要求時觸發組建，以及認可進入任何使用中提取要求的來源分支時。

pr:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

重要

當您指定 pr 觸發程式時，它會取代預設的隱含 pr 觸發程式，而且只會推送至明確設定為包含的分支會觸發管線。

如需需要排除特定分支的更複雜的觸發程式，您必須使用完整的語法，如下列範例所示。

# specific branch
pr:
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/old*

路徑

您可以指定要包含或排除的檔案路徑。 例如：

# specific path
pr:
  branches:
    include:
    - main
    - releases/*
  paths:
    include:
    - docs
    exclude:
    - docs/README.md

提示：

  • 路徑篩選不支援萬用字元。
  • 路徑一律會指定相對於存放庫根目錄。
  • 如果您未設定路徑篩選，則預設會隱含包含存放庫的根資料夾。
  • 如果您排除路徑，除非您將路徑限定為更深入的資料夾，否則也無法包含該路徑。 例如，如果您排除 /tools，則可以包含 /tools /trigger-runs-on-these
  • 路徑篩選的順序並不重要。
  • Git 中的路徑會區分大小寫 。 請務必使用與實際資料夾相同的案例。
  • 您無法在路徑中使用 變數 ，因為變數會在執行時間評估（觸發程式引發之後）。

多個 PR 更新

您可以指定 PR 的其他更新是否應該取消相同 PR 的進行中驗證執行。 預設值為 true。

# auto cancel false
pr:
  autoCancel: false
  branches:
    include:
    - main

退出宣告 PR 驗證

您可以藉由指定 pr: none 來完全退出提取要求驗證。

# no PR triggers
pr: none

如需詳細資訊，請參閱 YAML 架構 中的 PR 觸發程式 。

注意

pr如果您的觸發程式未引發，請確定您尚未 覆寫 UI 中的 YAML PR 觸發程式。

參考性執行

資訊執行會告訴您 Azure DevOps 無法擷取 YAML 管線的原始程式碼。 原始程式碼擷取會在回應外來事件時發生，例如推送的認可。 它也會在回應內部觸發程式時發生，例如，檢查是否有程式碼變更，並啟動排程的執行。 原始程式碼擷取可能會因為多個原因而失敗，而 Git 存放庫提供者經常要求節流。 資訊執行的存在不一定表示 Azure DevOps 會執行管線。

資訊執行看起來像在下列螢幕擷取畫面中。

Screenshot of an informational pipeline run.

您可以辨識下列屬性所執行的資訊：

  • 狀態為 Canceled
  • 持續時間為 < 1s
  • 執行名稱包含下列其中一個文字：
    • Could not retrieve file content for {file_path} from repository {repo_name} hosted on {host} using commit {commit_sha}.
    • Could not retrieve content for object {commit_sha} from repository {repo_name} hosted on {host}.
    • Could not retrieve the tree object {tree_sha} from the repository {repo_name} hosted on {host}.
    • Could not find {file_path} from repository {repo_name} hosted on {host} using version {commit_sha}. One of the directories in the path contains too many files or subdirectories.
  • 執行名稱通常包含導致 YAML 管線載入失敗的 BitBucket / GitHub 錯誤
  • 沒有階段 / 作業 / 步驟

深入瞭解 資訊執行 。

限制

Azure Pipelines 最多會將 2000 個分支從存放庫載入 Azure Devops 入口網站中的下拉式清單，例如手動和排程組建 設定的預設 分支，或在手動執行管線時選擇分支時。 如果您沒有在清單中看到所需的分支，請手動輸入所需的分支名稱。

常見問題集

與 Bitbucket 整合相關的問題分為下列類別：

  • 失敗的觸發程式 ： 當我將更新推送至存放庫時，我的管線不會觸發。
  • 錯誤版本 ： 我的管線執行，但它使用非預期的來源/YAML 版本。

失敗的觸發程式

我剛使用 CI/PR 觸發程式建立新的 YAML 管線，但不會觸發管線。

請遵循下列步驟來針對失敗的觸發程式進行疑難排解：

  • 您的 YAML CI 或 PR 觸發 程式是否由 UI 中的管線設定覆寫？ 編輯管線時，請選擇 ...，然後選擇 [ 觸發程式 ]。

    Pipeline settings UI.

    請從此處 檢查 [覆寫 YAML 觸發程式] 設定，以取得存放庫可用的觸發程式類型（ 持續整合 或 提取要求驗證 ）。

    Override YAML trigger from here.

  • Webhook 可用來將來自 Bitbucket 的更新通訊至 Azure Pipelines。 在 Bitbucket 中，流覽至存放庫的設定，然後流覽至 Webhook。 確認 Webhook 存在。

  • 管線已暫停或停用嗎？ 開啟管線的編輯器，然後選取 要檢查設定 。 如果您的管線已暫停或停用，則觸發程式無法運作。

  • 您是否已在正確的分支中更新 YAML 檔案？ 如果您將更新推送至分支，則相同分支中的 YAML 檔案會控管 CI 行為。 如果您將更新推送至來源分支，則合併來源分支與目標分支所產生的 YAML 檔案會控管 PR 行為。 請確定正確分支中的 YAML 檔案具有必要的 CI 或 PR 組態。

  • 您是否已正確設定觸發程式？ 當您定義 YAML 觸發程式時，您可以同時指定分支、標記和路徑的 include 和 exclude 子句。 請確定 include 子句符合認可的詳細資料，而且 exclude 子句不會排除這些子句。 檢查觸發程式的語法，並確定其正確無誤。

  • 您是否在定義觸發程式或路徑時使用變數？ 不支援。

  • 您是否使用 YAML 檔案的範本？ 如果是，請確定您的觸發程式定義于主要 YAML 檔案中。 不支援範本檔案內定義的觸發程式。

  • 您是否已排除您推送變更的分支或路徑？ 將變更推送至內含分支中的包含路徑，以進行測試。 請注意，觸發程式中的路徑會區分大小寫。 在指定觸發程式中的路徑時，請務必使用與實際資料夾相同的案例。

  • 您剛推送新分支嗎？ 如果是，新分支可能不會啟動新的執行。 請參閱一節。

我的 CI 或 PR 觸發程式正常運作。 但是，他們現在停止工作了。

請先完成上一個問題中的疑難排解步驟。 然後，請遵循下列其他步驟：

  • 您的 PR 中有合併衝突嗎？ 若為未觸發管線的 PR，請開啟它並檢查是否有合併衝突。 解決合併衝突。

  • 您遇到推送或 PR 事件的處理延遲嗎？ 您通常可查看問題是否專屬於單一管線，或是您專案中所有管線或存放庫通用，來確認此問題。 如果任何存放庫的推送或 PR 更新都表現出此徵兆，我們可能會遇到處理更新事件的延遲。 檢查我們狀態頁面上 是否有服務中斷 。 如果狀態頁面顯示問題，則我們的小組必須已經開始處理。 請經常檢查頁面，以取得問題的更新。

我不希望使用者在更新 YAML 檔案時覆寫觸發程式的分支清單。 如何執行此作業？

具有參與程式碼許可權的使用者可以更新 YAML 檔案，並包含/排除其他分支。 因此，使用者可以在 YAML 檔案中包含自己的功能或使用者分支，並將該更新推送至功能或使用者分支。 這可能會導致該分支的所有更新觸發管線。 如果您想要防止此行為，您可以：

  1. 在 Azure Pipelines UI 中編輯管線。
  2. 流覽至 [ 觸發程式] 功能表。
  3. 從這裡 選取 [覆寫 YAML 持續整合觸發程式]。
  4. 指定要包含或排除觸發程式的分支。

當您遵循這些步驟時，會忽略 YAML 檔案中指定的任何 CI 觸發程式。

錯誤的版本

管線中使用了錯誤的 YAML 檔案版本。 這是為什麼？

  • 針對 CI 觸發程式，系統會評估您要推送之分支中的 YAML 檔案，以查看是否應該執行 CI 組建。
  • 針對 PR 觸發程式，會評估合併 PR 來源和目標分支所產生的 YAML 檔案，以查看是否應該執行 PR 組建。