設定管線的排程

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Azure Pipelines 提供數種類型的觸發程式來設定管線的啟動方式。

  • 排程的觸發程式會根據排程啟動管線,例如夜間建置。 本文提供使用排程觸發程序根據排程執行管線的指引。
  • 事件型觸發程式會啟動管線以回應事件,例如建立提取要求或推送至分支。 如需使用事件型觸發程式的詳細資訊,請參閱 Azure Pipelines 中的觸發程式

您可以在管線中結合排程和事件型觸發程式,例如,在每次進行推送時驗證組建(CI 觸發程式)、提出提取要求時PR 觸發程式),以及夜間建置(已排程的觸發程式)。 如果您想要只依排程建置管線,而不是回應事件型觸發程式,請確定您的管線未啟用任何其他觸發程式。 例如,GitHub 存放庫中的 YAML 管線預設會啟用 CI 觸發程式和 PR 觸發程式。 如需停用預設觸發程式的資訊,請參閱 Azure Pipelines 中的觸發程式,並流覽至涵蓋存放庫類型的區段。

已排程的觸發程序

重要

使用管線設定 UI 定義的排程觸發程式優先於 YAML 排程觸發程式。

如果您的 YAML 管線同時有 YAML 排程觸發程序和 UI 定義的排程觸發程序,則只會執行 UI 定義的排程觸發程序。 若要在 YAML 管線中執行 YAML 定義的排程觸發程序,您必須移除管線設定 UI 中定義的已排程觸發程序。 拿掉所有 UI 排程觸發程式之後,必須進行推送,才能開始評估 YAML 排程觸發程式。

若要從 YAML 管線刪除 UI 排程的觸發程式,請參閱 UI 設定覆寫 YAML 排程觸發程式

排程的觸發程式會設定管線,以使用 cron語法所定義的排程執行。

schedules:
- cron: string # cron syntax defining a schedule
  displayName: string # friendly name given to a specific schedule
  branches:
    include: [ string ] # which branches the schedule applies to
    exclude: [ string ] # which branches to exclude from the schedule
  always: boolean # whether to always run the pipeline or only if there have been source code changes since the last successful scheduled run. The default is false.
schedules:
- cron: string # cron syntax defining a schedule
  displayName: string # friendly name given to a specific schedule
  branches:
    include: [ string ] # which branches the schedule applies to
    exclude: [ string ] # which branches to exclude from the schedule
  always: boolean # whether to always run the pipeline or only if there have been source code changes since the last successful scheduled run. The default is false.
  batch: boolean # Whether to run the pipeline if the previously scheduled run is in-progress; the default is false.
  # batch is available in Azure DevOps Server 2022.1 and higher

YAML 中的排程管線具有下列條件約束。

  • cron 排程的時區為UTC。
  • 如果您指定子exclude句而不include指定 子句branches,它相當於在 include 子句中指定 *
  • 指定排程時,您無法使用管線變數。
  • 如果您在 YAML 檔案中使用範本,則必須在主要 YAML 檔案中指定排程,而不是在範本檔案中指定。

排程觸發程式的分支考慮

當發生下列事件時,會評估分支的排程觸發程式。

  • 建立管線。
  • 管線的 YAML 檔案會從推送更新,或在管線編輯器中編輯它。
  • 管線的 YAML 檔案路徑會 更新為參考不同的 YAML 檔案。 這項變更只會更新預設分支,因此只會在預設分支的已更新 YAML 檔案中挑選排程。 如果後續有任何其他分支合併預設分支,例如 git pull origin main,則會針對該分支評估來自新參考 YAML 檔案的排程觸發程式。
  • 系統會建立新的分支。

在分支中發生其中一個事件之後,如果該分支符合該分支中 YAML 檔案中包含的已排程觸發程式的分支篩選條件,則會新增該分支的任何排程執行。

重要

只有當分支符合該特定分支中 YAML 檔案中排程觸發程式的分支篩選條件時,才會新增分支的排程執行。

例如,管線會使用下列排程建立,且此版本的 YAML 檔案會簽入 main 分支。 此排程會每天建 main 置分支。

# YAML file in the main branch
schedules:
- cron: '0 0 * * *'
  displayName: Daily midnight build
  branches:
    include:
    - main

接下來,會根據 main名為 new-feature的新分支來建立。 系統會讀取新分支中 YAML 檔案中的排程觸發程式,而且因為分支沒有相符 new-feature 專案,因此不會對排程的組建進行變更,而且 new-feature 不會使用排程的觸發程式來建置分支。

如果new-feature已新增至清單,且此變更會推送至branchesnew-feature分支,則會讀取 YAML 檔案,因為new-feature現在位於分支清單中,因此會新增分支的new-feature排程組建。

# YAML file in the new-feature-branch
schedules:
- cron: '0 0 * * *'
  displayName: Daily midnight build
  branches:
    include:
    - main
    - new-feature

現在,請考慮根據 建立main名為 release 的分支,然後將 release 新增至分支中 YAML 檔案main中的分支篩選,而不是在新建立release的分支中。

# YAML file in the release branch
schedules:
- cron: '0 0 * * *'
  displayName: Daily midnight build
  branches:
    include:
    - main

# YAML file in the main branch with release added to the branches list
schedules:
- cron: '0 0 * * *'
  displayName: Daily midnight build
  branches:
    include:
    - main
    - release

由於 release 已新增至分支中的 main 分支篩選,但 新增至分支中的 release 分支篩選, release 因此不會在該排程上建置分支篩選。 只有當分支新增至發行分支中 YAML 檔案中的分支篩選時release,排程的組建才會新增至排程器。

排程觸發程式的批次考慮

注意

屬性 batch 可在 Azure DevOps Server 2022.1 和更新版本上使用。

屬性 batch 會設定如果先前排程的執行正在進行中,是否要執行管線;預設值為 false。 這不論管線存放庫的版本為何。

下表描述和batch互動方式always

永遠 Batch 行為
false false 只有在上次成功排程的管線執行有所變更時,才會執行管線。
false true 只有在上次成功的排程管線執行有變更,而且沒有進行中的排程管線執行時,管線才會執行。
true false 管線會根據cron排程執行。
true true 管線會根據cron排程執行。

重要

當 是 truealways,管線會根據cron排程執行,即使 為 truebatch一定。

Build.CronSchedule.DisplayName 變數

注意

變數 Build.CronSchedule.DisplayName 可在 Azure DevOps Server 2022.1 和更新版本上使用。

當管線因為 cron 排程觸發程式而執行時,預先定義的 Build.CronSchedule.DisplayName 變數會 displayName 包含觸發管線執行之 cron 排程的 。

您的 YAML 管線可能包含多個 cron 排程,而且您可能希望管線根據 Cron 排程執行的不同階段或作業。 例如,您有夜間建置和每周建置,而您想要只在夜間建置期間執行特定階段。 您可以使用 Build.CronSchedule.DisplayName 作業或階段條件中的 變數來判斷是否要執行該作業或階段。

- stage: stage1
  # Run this stage only when the pipeline is triggered by the 
  # "Daily midnight build" cron schedule
  condition: eq(variables['Build.CronSchedule.DisplayName'], 'Daily midnight build')

如需更多範例,請參閱 schedules.cron 範例

Azure DevOps Server 2019 中的 YAML 語法不支援排程組建。 建立 YAML 組建管線之後,您可以使用管線設定來指定排程的觸發程式。

範例

下列範例會定義兩個排程:

schedules:
- cron: '0 0 * * *'
  displayName: Daily midnight build
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/ancient/*
- cron: '0 12 * * 0'
  displayName: Weekly Sunday build
  branches:
    include:
    - releases/*
  always: true

第一個排程:每日午夜建置會在每天午夜執行管線,但只有在上次成功排程執行main之後,程式代碼已變更,除了 下releases/ancient/*分支以外的所有releases/*分支。

第二個排程 :[每周星期天建置],會在星期日中午執行管線,不論程式代碼自上次執行以來是否已變更,都 releases/* 適用於所有分支。

注意

cron 排程的時區是UTC,因此在這些範例中,午夜組建和中午組建是UTC午夜和中午。

如需更多範例,請參閱 從傳統編輯器移轉。

Azure DevOps Server 2019 中的 YAML 語法不支援排程組建。 建立 YAML 組建管線之後,您可以使用管線設定來指定排程的觸發程式。

Cron 語法

每個 Azure Pipelines 排程的觸發程式 cron 運算式都是以空格分隔的表達式,其順序為五個專案。 表達式會以單引弧 '括住。

mm HH DD MM DW
 \  \  \  \  \__ Days of week
  \  \  \  \____ Months
   \  \  \______ Days
    \  \________ Hours
     \__________ Minutes
欄位 接受的值
分鐘 0 到 59
小時 0 到 23
1 到 31
1 到 12, 全英文名稱, 前三個字母的英文名稱
星期幾 0 到 6 (從星期日開始), 全英文名稱, 前三個字母的英文名稱

值可以是下列格式。

[格式] 範例 描述
萬用字元 * 符合此欄位的所有值
單一值 5 指定此欄位的單一值
逗號分隔 3,5,6 指定此欄位的多個值。 可以合併多種格式,例如 1,3-6
範圍 1-3 此欄位值的內含範圍
時間間隔 */41-5/2 要為此欄位比對的間隔,例如每四個值或範圍 1-5,步驟間隔為 2
範例 Cron 運算式
每週一、星期三和星期五下午 6:00 建置 0 18 * * Mon,Wed,Fri0 18 * * 1,3,50 18 * * 1-5/2
每隔 6 小時建置一次 0 0,6,12,18 * * *0 */6 * * *0 0-18/6 * * *
從上午 9:00 開始每隔 6 小時建置一次 0 9,15,21 * * *0 9-21/6 * * *

如需支援格式的詳細資訊,請參閱 Crontab 表達式

Azure DevOps Server 2019 中的 YAML 語法不支援排程組建。 建立 YAML 組建管線之後,您可以使用管線設定來指定排程的觸發程式。

排程的執行檢視

您可以從管線詳細數據頁面的操作功能表中選擇 [排程執行],以檢視即將推出的排程組建預覽。

重要

排程的執行檢視只會顯示排程在目前日期七天內執行的管線。 如果您的cron排程的間隔超過7天,且下一次執行排程會排定在從目前日期起七天后開始,則不會顯示在排程的執行檢視中。

排程的執行功能表

建立或更新排程的觸發程序之後,您可以使用此檢視來驗證它們。

排程的執行

此範例會顯示下列排程的排程執行。

schedules:
- cron: '0 0 * * *'
  displayName: Daily midnight build
  branches:
    include:
    - main

[ 排程執行 ] 視窗會顯示用來流覽至 Azure DevOps 入口網站之計算機上所設定之本機時區的轉換時間。 此範例會顯示在 EST 時區中擷取的螢幕快照。

Azure DevOps Server 2019 中的 YAML 語法不支援排程組建。 建立 YAML 組建管線之後,您可以使用管線設定來指定排程的觸發程式。

即使沒有任何程式代碼變更,仍執行

根據預設,如果您的管線在上次成功排程執行之後沒有程式代碼變更,則不會依排程執行排程執行。 例如,假設您已排程在晚上 9:00 執行管線。 在工作日期間,您會將各種變更推送至程序代碼。 管線會依排程執行。 在週末,您不會對程式代碼進行任何變更。 如果自上週五排程執行之後沒有程式碼變更,管線就不會在週末如期執行。

若要強制管線執行,即使沒有任何程式碼變更,您也可以使用 always 關鍵詞。

schedules:
- cron: ...
  ...
  always: true

此版本的 Azure DevOps Server 中,YAML 語法不支援排程的組建。 建立 YAML 組建管線之後,您可以使用管線設定來指定排程的觸發程式。

YAML 管線中排程執行數目的限制

排程管線執行的頻率有一些限制。 實施這些限制是為了防止 Azure Pipelines 資源遭到濫用,特別是裝載 Microsoft 的代理程式。 這些限制是:

  • 每週大約 1000 個管線執行
  • 每 15 分鐘每個管線 10 次執行

從傳統編輯器移轉

下列範例示範如何將排程從傳統編輯器移轉至 YAML。

範例:在多個時區中夜間建置 Git 存放庫

在此範例中,傳統編輯器排程觸發程式有兩個專案,會產生下列組建。

  • 每個星期一 - 星期五上午 3:00 (UTC + 5:30 時區),建置符合分支篩選準則的 features/india/* 分支

    排程觸發程式 UTC + 5:30 時區

  • 每個星期一 - 星期五上午 3:00 (UTC - 5:00 時區),建置符合分支篩選準則的 features/nc/* 分支

    排程觸發程式 UTC -5:00 時區

對等的 YAML 排程觸發程式為:

schedules:
- cron: '30 21 * * Sun-Thu'
  displayName: M-F 3:00 AM (UTC + 5:30) India daily build
  branches:
    include:
    - /features/india/*
- cron: '0 8 * * Mon-Fri'
  displayName: M-F 3:00 AM (UTC - 5) NC daily build
  branches:
    include:
    - /features/nc/*

在第一個排程中, M-F 上午 3:00 (UTC + 5:30) 印度每日建置,cron 語法 (mm HH DD MM DW) 為 30 21 * * Sun-Thu

  • 分鐘和小時 - 30 21 這會對應至 21:30 UTC9:30 PM UTC)。 由於傳統編輯器中指定的時區是 UTC + 5:30,因此我們需要從上午3:00的所需建置時間減去5小時30分鐘,才能到達指定YAML觸發程式的所需UTC時間。
  • 天數和月份會指定為通配符,因為此排程不會指定只在月份的特定天數或特定月份執行。
  • 星期幾 - 由於 Sun-Thu 時區轉換,我們的組建在UTC + 5:30印度時區的上午3:00執行,我們需要指定從UTC時間的前一天開始。 我們也可以將星期幾指定為 0-40,1,2,3,4

在第二個排程中, M-F 上午 3:00(UTC - 5) NC 每日建置,cron 語法為 0 8 * * Mon-Fri

  • 分鐘與小時 ─ 0 8 這會對應至 8:00 AM UTC。 由於傳統編輯器中的指定時區是 UTC - 5:00,因此我們需要從上午 3:00 的所需建置時間新增5小時,才能到達所需的UTC時間,以指定YAML觸發程式。
  • 天數和月份會指定為通配符,因為此排程不會指定只在月份的特定天數或特定月份執行。
  • 一周中的天數 - Mon-Fri 由於我們的時區轉換不會針對所需的排程跨越一周中的多天,因此我們不需要在這裡進行任何轉換。 我們也可以將星期幾指定為 1-51,2,3,4,5

重要

YAML 排程觸發程式中的 UTC 時區不會考慮日光節約時間。

提示

當使用一周的 3 個字母天,並想要透過 Sun 跨越多個天時,Sun 應該視為一周的第一天,例如,對於週四到星期日午夜的排程,cron 語法為 0 5 * * Sun,Thu-Sat

範例:使用不同頻率的夜間建置

在此範例中,傳統編輯器排程觸發程式有兩個專案,會產生下列組建。

  • 每個星期一 - 星期五上午 3:00 UTC,建置符合 和 releases/* 分支篩選準則的main分支

    排程的觸發程序頻率 1。

  • 每個星期天上午 3:00 UTC,建 releases/lastversion 置分支,即使來源或管線尚未變更

    排程的觸發程序頻率 2。

對等的 YAML 排程觸發程式為:

schedules:
- cron: '0 3 * * Mon-Fri'
  displayName: M-F 3:00 AM (UTC) daily build
  branches:
    include:
    - main
    - /releases/*
- cron: '0 3 * * Sun'
  displayName: Sunday 3:00 AM (UTC) weekly latest version build
  branches:
    include:
    - /releases/lastversion
  always: true

在第一個排程中, M-F 上午 3:00(UTC) 每日建置,cron 語法為 0 3 * * Mon-Fri

  • 分鐘與小時 ─ 0 3 這會對應至 3:00 AM UTC。 由於傳統編輯器中的指定時區是 UTC,因此我們不需要進行任何時區轉換。
  • 天數和月份會指定為通配符,因為此排程不會指定只在月份的特定天數或特定月份執行。
  • 星期幾 - 由於 Mon-Fri 沒有時區轉換,因此一周中的天數會直接從傳統編輯器排程對應。 我們也可以將星期幾指定為 1,2,3,4,5

在第二個排程中, 星期天上午 3:00 (UTC) 每週最新版本組建,cron 語法為 0 3 * * Sun

  • 分鐘與小時 ─ 0 3 這會對應至 3:00 AM UTC。 由於傳統編輯器中的指定時區是 UTC,因此我們不需要進行任何時區轉換。
  • 天數和月份會指定為通配符,因為此排程不會指定只在月份的特定天數或特定月份執行。
  • 一周中的天數 - Sun 由於我們的時區轉換不會針對所需的排程跨越一周中的多天,因此我們不需要在這裡進行任何轉換。 我們也可以將星期幾指定為 0
  • 我們也指定 always: true ,因為此組建已排程執行原始程式碼是否已更新。

常見問題集

我希望我的管線只在排程上執行,而不是當有人將變更推送至分支時

如果您希望管線只在排程上執行,而不是當有人將變更推送至分支或合併主要分支的變更時,您必須明確停用管線上的預設 CI 和 PR 觸發程式。

若要停用預設 CI 和 PR 觸發程式,請將下列語句新增至 YAML 管線,並 確認您尚未使用 UI 觸發程式覆寫 YAML 管線觸發程式

trigger: none
pr: none

如需詳細資訊,請參閱 pr定義觸發程式定義

我在 YAML 檔案中定義了排程。 但它沒有運行。 發生什麼事?

  • 檢查 Azure Pipelines 已針對管線排程的後續幾個執行。 您可以在管線中選取 [已排程的執行] 動作來尋找這些執行 。 清單會篩選為只顯示未來幾天的後續執行。 如果不符合您的預期,可能是您輸入cron排程錯誤,或未在正確的分支中定義排程。 請閱讀上述主題,以瞭解如何設定排程。 重新評估您的cron語法。 cron 排程的所有時間都是UTC。

  • 對 YAML 檔案進行小型變更,並將該更新推送至您的存放庫。 如果先前從 YAML 檔案讀取排程時發生任何問題,現在應該加以修正。

  • 如果您在 UI 中定義了任何排程,則您的 YAML 排程不會接受。 流覽至管線的編輯器,然後選取 [觸發程式],確定您沒有任何UI排程。

  • 您可以排程管線的執行數目有限制。 深入瞭解 限制

  • 如果您的程式代碼沒有變更,Azure Pipelines 可能無法啟動新的執行。 瞭解如何 覆寫 此行為。

我的 YAML 排程正常運作。 但是,他們現在停止工作了。 如何? 對此進行偵錯?

  • 如果您未指定 always:true,除非您對程式代碼進行任何更新,否則不會排程您的管線。 檢查是否有任何程式代碼變更,以及您 設定排程的方式。

  • 您可以排程管線的次數有限制。 檢查您是否已超過這些限制。

  • 檢查是否有人在UI中啟用更多排程。 開啟管線的編輯器,然後選取 [ 觸發程式]。 如果他們在UI中定義排程,則不會接受您的YAML排程。

  • 檢查您的管線是否已暫停或停用。 選取管線 設定

  • 檢查 Azure Pipelines 已針對管線排程的後續幾個執行。 您可以在管線中選取 [已排程的執行] 動作來尋找這些執行 。 如果您沒有看到預期的排程,請對 YAML 檔案進行小型的變更,並將更新推送至您的存放庫。 這應該會重新同步排程。

  • 如果您使用 GitHub 來儲存程式代碼,則 Azure Pipelines 可能會在嘗試啟動新的執行時受到 GitHub 的節流。 檢查您是否可以手動啟動新的執行。

我的程式代碼尚未變更,但已觸發排程的組建。 為什麼?

  • 您可能已啟用一個選項, 一律 執行排程的組建,即使沒有任何程式碼變更也一樣。 如果您使用 YAML 檔案,請確認 YAML 檔案中排程的語法。 如果您使用傳統管線,請確認您已在排程的觸發程式中核取此選項。

  • 您可能已更新組建管線或管線的某些屬性。 這會導致排程新的執行,即使您尚未更新原始程式碼也一樣。 使用傳統編輯器確認管線中變更的歷程記錄

  • 您可能已更新用來連線至存放庫的服務連線。 這會導致排程新的執行,即使您尚未更新原始程式碼也一樣。

  • Azure Pipelines 會先檢查您的程式代碼是否有任何更新。 如果 Azure Pipelines 無法連線到您的存放庫或取得此資訊,則會建立 資訊執行。 這是一個虛擬組建,可讓您知道 Azure Pipelines 無法連線到您的存放庫。

  • 您的管線可能沒有完全成功的建置。 為了判斷是否要排程新的組建,Azure DevOps 會查閱最後一個完全成功的排程組建。 如果找不到,則會觸發新的排程組建。 部分成功的排程組建不會被視為成功,因此,如果您的管線只有部分成功的組建,即使您的程式代碼尚未變更,Azure DevOps 也會觸發排程的組建。

我在 [排程的執行] 面板中看到已規劃的執行。 不過,它當時不會執行。 為什麼?

  • [ 排程的執行] 面板會顯示所有可能的排程。 不過,除非您已對程式代碼進行真正的更新,否則它可能不會實際執行。 若要強制排程一律執行,請確定您已在 YAML 管線中設定 always 屬性,或核取選項以一律在傳統管線中執行。

排程 YAML 管線中定義的一個分支工作,但不是另一個分支。 如何修正此問題?

排程定義於 YAML 檔案中,且這些檔案會與分支相關聯。 如果您想要為特定分支排程管線,例如 features/X,請確定該分支中的 YAML 檔案已定義 cron 排程,而且其具有排程的正確分支包含。 分支中的 features/X YAML 檔案應該在此範例中具有下列專案 schedule

schedules: 
- cron: '0 12 * * 0'   # replace with your schedule
  branches: 
    include: 
    - features/X  

如需詳細資訊,請參閱 排程觸發程式的分支考慮。