設定管線的排程
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 or pipeline settings 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 or pipeline settings 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。 您可以使用 GitHub Copilot 的 AI 協助來創建 cron 表達式。
- 如果您為
branches
指定exclude
子句,但沒有include
子句,則相當於在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
新增至 branches
清單,並將這項變更推送至 new-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
新增至 main
分支中 YAML 檔案中的分支篩選,但在新建立的 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
分支不會根據該排程建置。 只有在 release
分支新增到 YAML 文件 中的分支篩選並且位於發行分支 時,排程的組建才會被加入到排程器中。
排程觸發程式的批次處理考量
備註
Azure DevOps Server 2022.1 和更新版本提供 batch
屬性。
batch
屬性設定是否要在先前排定的執行正在進行中時啟動管線。 當 batch
true
時,如果先前的管線執行仍在進行中,新的管線執行將不會因為排程而啟動。 預設值為 false
。
batch
屬性會受到 always
屬性的設定所影響。 當 always
是 true
時,管線會根據 cron 排程運行,即便 batch
是 true
且有正在進行的執行。
永遠 | 批次 | 行為 |
---|---|---|
false |
false |
只有當與上次成功的排程管線執行相比有變更時,管線才會執行,即使上次排程的觸發所導致的管線執行仍在進行中也不例外。 |
false |
true |
只有在上次成功的排程管線執行有變更,而且沒有進行中的排程管線執行時,管線才會執行。 |
true |
false |
管線會根據 cron 時間表執行。 |
true |
true |
即使有進行中的執行,管線仍會根據「cron」排程執行。 |
Build.CronSchedule.DisplayName 變數
備註
azure DevOps Server 2022.1 和更新版本提供 Build.CronSchedule.DisplayName
變數。
當管線因為 cron 排程觸發而執行時,預先定義的 Build.CronSchedule.DisplayName
變數會包含觸發管線執行的 cron 排程的 displayName
。
您的 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: '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
第一個排程,每日午夜組建,每天午夜執行流程,但僅在程式碼自上次排程成功執行後已變更的情況下啟動,適用於除了 releases/ancient/*
下的分支以外的 main
和所有 releases/*
分支。
第二個排程,每週日的建置,會在每個星期日中午執行管線,無論自上次執行以來程式代碼是否已變更,適用於所有 releases/*
分支。
備註
cron 排程的時區是 UTC,因此在這些範例中,午夜構建和中午構建是在 UTC 時間的午夜和正午。
如需更多範例,請參閱 從傳統編輯器移轉。
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 |
此欄位值的內含範圍 |
時間間隔 |
*/4 或 1-5/2 |
符合此欄位的間隔,例如每四個值或範圍 1-5,步距為 2。 |
範例 | Cron 運算式 |
---|---|
每週一、星期三和星期五下午 6:00 建置 |
0 18 * * Mon,Wed,Fri 、 0 18 * * 1,3,5 或 0 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 表示式。
使用 GitHub Copilot 建立 cron 運算式
您可以從 GitHub Copilot 取得 AI 協助,以建置 cron 運算式,或將現有的 cron 運算式從當地時區轉換為 UTC。
Azure Pipelines cron 排程是以 UTC 定義,因此 組建等排程,例如每週一、星期三和星期五下午 6:00 必須使用 cron 語法建立,然後從當地時區轉換成 UTC。
自定義下列提示以建立cron表達式,或從您用來建立表達式的時區將cron運算式轉換成UTC。
在下列範例中,系統會提示 Copilot 建立 UTC cron 排程,以在每個星期一、星期三和星期五下午 6:00 東部標準時間建置。
Build a UTC cron expression for Monday, Wednesday, and Friday at 6:00 PM Eastern Standard Time
如果您的當地時區已經有cron表達式,您可以要求 Copilot 將它轉換成 UTC。 在此範例中,每週一、週三和週五下午 6:00(0 18 * * Mon,Wed,Fri
)Eastern Standard Time 的 cron 排程會轉換成 UTC。
Convert the following cron expression from Eastern Standard Time to UTC: 0 18 * * Mon,Wed,Fri
將cron表達式轉換成UTC可能需要變更表達式中的星期幾。 在下列範例中,Copilot 被提示建立一個 UTC cron 排程,以便從星期一到星期五在中歐標準時間凌晨 12:30 執行。 中歐標準時間領先 UTC,因此產生的表達式會在周日深夜開始,而不是週一清晨,並在週四結束。
Build a UTC cron expression for Monday through Friday at 12:30 AM Central European Standard Time
若要取得 Copilot 所產生的 cron 表達式的其他詳細數據,您可以要求 Copilot 在提示中提供所產生 cron 表達式的說明。
Build a UTC cron expression for Monday through Friday at 12:30 AM Central European Standard Time and explain the different parts of the cron expression
Copilot 是由 AI 所提供,因此可能會有驚喜和錯誤。 如需詳細資訊,請參閱 Copilot 一般使用常見問題。
排程運行檢視
您可以從您的管線 管線詳細頁面 的內容功能表中選擇 [排程運行],以檢視即將到來的排程組建預覽。
這很重要
排程執行檢視只會顯示從目前日期起算的七天內排程執行的管線。 如果您的cron排程的間隔時間超過7天,且下一次執行排程會在從目前日期起七天后開始,則不會顯示在 排程執行 檢視中。
建立或更新排程觸發程序之後,您可以使用 排程執行 檢視來驗證它們。
此範例顯示下列排程的預定執行任務。
schedules:
- cron: '0 0 * * *'
displayName: Daily midnight build
branches:
include:
- main
排程顯示 視窗會顯示轉換成用於瀏覽 Azure DevOps 入口網站的電腦上設定的本機時區的時間。 此範例會顯示在 EST 時區中擷取的螢幕快照。
備註
如果您更新執行中管線的排程,排程視圖 不會隨之更新新排程,直到目前執行中的管線完成為止。
即使沒有任何程式代碼變更,仍執行
根據預設,如果自上次成功的排程執行以來程式代碼沒有變更,您的管線將不會依排程執行。 例如,假設您已排程在晚上 9:00 執行管道的工作。 在工作日期間,您會將各種變更推送至程式碼。 管線會依排程執行。 在週末,您不會對程式代碼進行任何變更。 如果自上週五排程執行以來沒有程式碼變更,管線就不會在週末按計畫執行。
YAML 管線中排程執行數目的限制
排程管線的執行頻率有一些限制。 實施這些限制是為了防止 Azure Pipelines 資源遭到濫用,特別是裝載 Microsoft 的代理程式。 這些限制是:
- 每條管線每週約有 1000 次執行
- 每個管線每 15 分鐘執行 10 次
從傳統編輯器移轉
下列範例示範如何將排程從傳統編輯器移轉至 YAML。
範例:在多個時區中夜間建置 Git 存放庫
在此範例中,經典編輯器排程觸發有兩個條目,會產生下列建置內容。
每個星期一—星期五上午 3:00(UTC + 5:30 時區),建置符合
features/india/*
分支篩選準則的分支每個星期一 - 星期五上午 3:00 (UTC - 5:00 時區),建置符合
features/nc/*
分支篩選準則的分支
等效的 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/*
在第一個排程中,週一至週五凌晨3:00(UTC + 5:30)印度每日構建,cron 語法(mm HH DD MM DW
)是 30 21 * * Sun-Thu
。
- 分鐘和小時 -
30 21
- 這對應至21:30 UTC
(9:30 PM UTC
)。 由於傳統編輯器中的指定時區 UTC + 5:30,因此我們需要從所需的建置時間 3:00 AM 減去 5 小時 30 分鐘,才能到達指定 YAML 觸發程式的所需 UTC 時間。 您可以從 GitHub Copilot 取得 AI 協助,以建立 cron 表達式。 - 天數和月份會指定為通配符,因為此排程不會指定只在月份的特定天數或特定月份執行。
- 星期幾 -
Sun-Thu
- 由於時區轉換,為了讓我們的構建能在UTC+5:30的印度時區於凌晨3:00執行,我們需要在UTC時間中將它們安排在前一天開始。 我們也可以將星期幾指定為0-4
或0,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 觸發程式。 您可以從 GitHub Copilot 取得 AI 協助,以建立 cron 表達式。 - 天數和月份會指定為通配符,因為此排程不會指定只在月份的特定天數或特定月份執行。
- 一周中的天數 -
Mon-Fri
- 因為我們的時區轉換不會跨越一周中的多個天,因此我們不需要在這裡進行任何轉換。 我們也可以將星期幾指定為1-5
或1,2,3,4,5
。
這很重要
YAML 排程觸發程式中的 UTC 時區不會考慮日光節約時間。
小提示
在使用一週日子的三個字母縮寫時,如果要將多個天數延續至週日,則週日應視為一週之始。舉例來說,對於東部標準時間午夜從週四到週日的排程,cron 語法是 0 5 * * Sun,Thu-Sat
。
範例:使用不同頻率的夜間建置
在此範例中,傳統編輯器排程的觸發器有兩個項目,會產生下列建置。
每個星期一 - 星期五上午 3:00 UTC,建置符合
main
和releases/*
分支篩選準則的分支每周日上午 3:00 UTC,建置
releases/lastversion
分支,即使來源或管線未變更
對應的 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
,因為無論原始程式碼是否已更新,此建置都已排程執行。
常見問題
- 我希望我的佇列只依據排程進行,而不是當有人將變更提交至分支
- 我在 YAML 檔案中定義了排程。 但它沒有運行。 發生什麼事?
- 我的 YAML 排程正常運作。 但是,他們現在停止工作了。 如何進行偵錯?
- 我的程式代碼尚未變更,但已觸發排程的組建。 為什麼?
- 我在 [排程執行面板] 中看到已規劃的執行。 不過,它當時沒有運行。 為什麼?
- 在 YAML 管線中定義的排程對其中一個分支有效,但對另一個分支無效。 我要如何修正此問題?
我希望我的管線僅依照排程執行,而不是當有人將變更推送至分支時
如果您希望管線只有在排定的時間執行,而不是當有人推送變更至分支或合併至主分支時,您必須明確關閉管線上的預設 CI 和 PR 觸發程式。
若要停用預設 CI 和 PR 觸發程式,請將下列語句新增至 YAML 管線,確認您尚未使用 UI 觸發程式覆寫 YAML 管線觸發程式,。
trigger: none
pr: none
我在 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 管線中設定 一律 屬性,或在傳統管線中選擇一律執行的選項。
在 YAML 管線中定義的排程對一個分支有效,但對另一個分支無效。 我要如何修正此問題?
排程定義於 YAML 檔案中,且這些檔案會與分支相關聯。 如果您想要為特定分支排程管線,例如 features/X
,請確定該分支中的 YAML 檔案 已定義 cron 排程,而且其具有排程的正確分支包含。
features/X
分支中的 YAML 檔案在此範例中應具有下列 schedule
:
schedules:
- cron: '0 12 * * 0' # replace with your schedule
branches:
include:
- features/X
如需詳細資訊,請參閱 排程觸發程式的分支考慮。