Merging changes synced from https://github.com/MicrosoftDocs/azure-devops-docs-pr (branch live)

Author: Learn Build Service GitHub App

docs/pipelines/process/stages.md

@@ -3,15 +3,15 @@ title: Stages in Azure Pipelines
 description: Learn how to organize your jobs into stages, define dependencies, and set conditions. Understand how to implement deployment strategies and use YAML or a Classic pipeline to define stages.
 ms.assetid: FAAD6503-F8CE-4F5D-8C1E-83AF6E903568
 ms.topic: conceptual
-ms.date: 02/16/2024
+ms.date: 03/28/2025
 monikerRange: '<= azure-devops'
 ---
 
-# Add stages, dependencies, & conditions  
+# Add stages, dependencies, and conditions  
 
 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)]
 
-A stage is a logical boundary in an Azure DevOps pipeline. Stages can be used to group actions in your software development process (for example, build the app, run tests, deploy to preproduction). Each stage contains one or more jobs. 
+A stage is a logical boundary in an Azure DevOps pipeline. Stages group actions in your software development process, like building the app, running tests, and deploying to preproduction. Each stage contains one or more jobs. 
 
 When you define multiple stages in a pipeline, by default, they run one after the other. Stages can also depend on each other. You can use the `dependsOn` keyword to define [dependencies](#specify-dependencies). Stages also can run based on the result of a previous stage with [conditions](#conditions). 
 
@@ -26,13 +26,13 @@ You can also learn more about how stages relate to parts of a pipeline in the [Y
 
 You can organize pipeline jobs into stages. Stages are the major divisions in a pipeline: build this app, run these tests, and deploy to preproduction are good examples of stages. They're logical boundaries in your pipeline where you can pause the pipeline and perform various checks.
 
-Every pipeline has at least one stage even if you don't explicitly define it. You can also arrange stages into a dependency graph so that one stage runs before another one. There's a limit of 256 jobs for a stage. 
+Every pipeline has at least one stage, even if you don't explicitly define it. You can also arrange stages into a dependency graph so that one stage runs before another one. A stage can have up to 256 jobs. 
 
 ::: moniker-end
 
 #### [Classic](#tab/classic/)
 Organize the deployment jobs in your release pipeline into stages.
-Stages are the major divisions in your release pipeline: run functional tests, deploy to preproduction, and deploy to production are good examples of release stages.
+Stages are the major divisions in your release pipeline. Examples include running functional tests, deploying to preproduction, and deploying to production.
 
 <a name="approvals"></a><a name="conditions"></a>
 A stage in a release pipeline consists of [jobs](../process/phases.md) and [tasks](../process/tasks.md).
@@ -50,49 +50,72 @@ and [queuing policies](#queuing-policies) control when a release gets deployed t
 
 ::: moniker range="<=azure-devops"
 
-In the simplest case, you don't need any logical boundaries in your pipeline. In that case, you don't have to explicitly use the `stage` keyword. You can directly specify the jobs in your YAML file.
+In the simplest case, you don't need logical boundaries in your pipeline. For those scenarios, you can directly specify the jobs in your YAML file without the `stages` keyword. For example, if you have a simple pipeline that builds and tests a small application without requiring separate environments or deployment steps, you can define all the jobs directly without using stages.
 
 ```yaml
-# this has one implicit stage and one implicit job
 pool:
   vmImage: 'ubuntu-latest'
-steps:
-- bash: echo "Hello world"
+
+jobs:
+- job: BuildAndTest
+  steps:
+  - script: echo "Building the application"
+  - script: echo "Running tests"
 ```
 
+This pipeline has one implicit stage and two jobs. The `stages` keyword isn't used because there's only one stage. 
+
 ```yaml
-# this pipeline has one implicit stage
 jobs:
-- job: A
+- job: Build
   steps:
-  - bash: echo "A"
+  - bash: echo "Building"
 
-- job: B
+- job: Test
   steps:
-  - bash: echo "B"
+  - bash: echo "Testing"
 ```
 
-If you organize your pipeline into multiple stages, you use the `stages` keyword.
+To organize your pipeline into multiple stages, use the `stages` keyword. This YAML defines a pipeline with two stages where each stage contains multiple jobs, and each job has specific steps to execute.
 
 ```yaml
 stages:
 - stage: A
+  displayName: "Stage A - Build and Test"
   jobs:
   - job: A1
+    displayName: "Job A1 - build"
+    steps:
+    - script: echo "Building the application in Job A1"
+      displayName: "Build step"
   - job: A2
+    displayName: "Job A2 - Test"
+    steps:
+    - script: echo "Running tests in Job A2"
+      displayName: "Test step"
 
 - stage: B
+  displayName: "Stage B - Deploy"
   jobs:
   - job: B1
+    displayName: "Job B1 - Deploy to Staging"
+    steps:
+    - script: echo "Deploying to staging in Job B1"
+      displayName: "Staging deployment step"
   - job: B2
+    displayName: "Job B2 - Deploy to Production"
+    steps:
+    - script: echo "Deploying to production in Job B2"
+      displayName: "Production deployment step"
 ```
 
-If you choose to specify a `pool` at the stage level, then all jobs defined in that stage use that pool unless specified at the job-level.
-
 ::: moniker-end
 
 ::: moniker range="<=azure-devops"
 
+If you specify a `pool` at the stage level, all jobs in that stage use that pool unless the stage is specified at the job level.
+
+
 ```yaml
 stages:
 - stage: A
@@ -103,24 +126,12 @@ stages:
     pool: JobPool
 ```
 
-The full syntax to specify a stage is:
-
-```yaml
-stages:
-- stage: string  # name of the stage, A-Z, a-z, 0-9, and underscore
-  displayName: string  # friendly name to display in the UI
-  dependsOn: string | [ string ]
-  condition: string
-  pool: string | pool
-  variables: { string: string } | [ variable | variableReference ] 
-  jobs: [ job | templateReference]
-```
 
 ::: moniker-end
 
 #### [Classic](#tab/classic/)
 
-To add a stage to your release pipeline, select the release pipeline in **Releases** page, select the action to **Edit** it, and then select the **Pipeline** tab.
+To add a stage to your release pipeline, select the release pipeline on the **Releases** page, select **Edit**, and then select the **Pipeline** tab.
 While the most important part of defining a stage is the
 automation tasks, you can also configure several properties and options
 for a stage in a release pipeline. You can:
@@ -129,7 +140,7 @@ for a stage in a release pipeline. You can:
 * Designate one user or a 
   group to be the stage owner. Stage owners get
   notified whenever a deployment to that
-  stage fails. Being a stage owner doesn't automatically come with any permissions. 
+  stage fails. Stage ownership doesn't automatically include permissions. 
 * Delete the stage from the pipeline.
 * Change the order of stages.
 * Save a copy of the stage as a [stage template](../release/env-templates.md).
@@ -145,77 +156,82 @@ for a stage in a release pipeline. You can:
 
 ::: moniker range="<=azure-devops"
 
-When you define multiple stages in a pipeline, by default, they run sequentially in the order in which you define them in the YAML file. The exception to this is when you add dependencies. With dependencies, stages run in the order of the `dependsOn` requirements. 
+When you define multiple stages in a pipeline, they run sequentially by default in the order you define them in the YAML file. The exception to this is when you add dependencies. With dependencies, stages run in the order of the `dependsOn` requirements. 
 
 Pipelines must contain at least one stage with no dependencies.
 
-The syntax for defining multiple stages and their dependencies is:
+For more information on how to define stages, see [stages in the YAML schema](/azure/devops/pipelines/yaml-schema/stages). 
 
-```yaml
-stages:
-- stage: string
-  dependsOn: string
-  condition: string
-```
+The following example stages run sequentially. If you don't use a `dependsOn` keyword, stages run in the order they're defined. 
 
-Example stages that run sequentially:
 
 ```yaml
-# if you do not use a dependsOn keyword, stages run in the order they are defined
 stages:
-- stage: QA
+- stage: Build
+  displayName: "Build Stage"
   jobs:
-  - job:
-    ...
+  - job: BuildJob
+    steps:
+    - script: echo "Building the application"
+      displayName: "Build Step"
 
-- stage: Prod
+- stage: Test
+  displayName: "Test Stage"
   jobs:
-  - job:
-    ...
+  - job: TestJob
+    steps:
+    - script: echo "Running tests"
+      displayName: "Test Step"
 ```
 
 Example stages that run in parallel:
 
 ```yaml
 stages:
 - stage: FunctionalTest
+  displayName: "Functional Test Stage"
   jobs:
-  - job:
-    ...
+  - job: FunctionalTestJob
+    steps:
+    - script: echo "Running functional tests"
+      displayName: "Run Functional Tests"
 
 - stage: AcceptanceTest
-  dependsOn: []    # this removes the implicit dependency on previous stage and causes this to run in parallel
+  displayName: "Acceptance Test Stage"
+  dependsOn: [] # Runs in parallel with FunctionalTest
   jobs:
-  - job:
-    ...
+  - job: AcceptanceTestJob
+    steps:
+    - script: echo "Running acceptance tests"
+      displayName: "Run Acceptance Tests"
 ```
 
-Example of fan-out and fan-in:
+Example of fan-out and fan-in behavior:
 
 ```yaml
 stages:
 - stage: Test
 
 - stage: DeployUS1
-  dependsOn: Test    # this stage runs after Test
+  dependsOn: Test    #  stage runs after Test
 
 - stage: DeployUS2
-  dependsOn: Test    # this stage runs in parallel with DeployUS1, after Test
+  dependsOn: Test    # stage runs in parallel with DeployUS1, after Test
 
 - stage: DeployEurope
-  dependsOn:         # this stage runs after DeployUS1 and DeployUS2
+  dependsOn:         # stage runs after DeployUS1 and DeployUS2
   - DeployUS1
   - DeployUS2
 ```
 
 ::: moniker-end
 
 #### [Classic](#tab/classic/)
-You control the dependencies by setting the triggers on each stage of the release pipeline:
+Control dependencies by setting triggers on each stage of the release pipeline:
 
-* Stages run with a trigger or by being manually started. 
-* With an **After release** trigger, a stage starts as soon as the release starts, in parallel with other stages that have **After release** trigger.
-* With an **After stage** trigger, a stage will start after all the dependent stages complete. Using this, you can model fan-out and fan-in behavior for stages.
+* Stages run with a trigger or are manually started. 
+* With an **After release** trigger, a stage starts as soon as the release begins, running in parallel with other stages that have the same trigger.
+* With an **After stage** trigger, a stage starts after all dependent stages complete. Using this, you can model fan-out and fan-in behavior for stages.
 
 * * *
 
@@ -275,12 +291,12 @@ When you specify **After release** or **After stage** triggers, you can also spe
 
 #### [YAML](#tab/yaml/)
 ::: moniker range="<=azure-devops"
-YAML pipelines don't support queuing policies. Each run of a pipeline is independent from and unaware of other runs. In other words, your two successive commits may trigger two pipelines, and both of them will execute the same sequence of stages without waiting for each other. While we work to bring queuing policies to YAML pipelines, we recommend that you use [manual approvals](approvals.md) in order to manually sequence and control the order the execution if this is of importance.
+YAML pipelines don't support queuing policies. Each run of a pipeline is independent from and unaware of other runs. In other words, your two successive commits might trigger two pipelines, and both of them will execute the same sequence of stages without waiting for each other. While we work to bring queuing policies to YAML pipelines, we recommend that you use [manual approvals](approvals.md) in order to manually sequence and control the order the execution if this is of importance.
 ::: moniker-end
 
 #### [Classic](#tab/classic/)
-In some cases, you may be able to generate builds faster than
-they can be deployed. Alternatively, you may configure multiple
+In some cases, you might be able to generate builds faster than
+they can be deployed. Alternatively, you might configure multiple
 [agents](../agents/agents.md) and, for example, be creating releases from the same release pipeline
 for deployment of different artifacts. In such cases, it's useful to
 be able to control how multiple releases are queued into a
@@ -370,14 +386,14 @@ In the following example, the development stage runs automatically, while the pr
 
 ```yaml
 stages:
-- stage: development
+- stage: Development
   displayName: Deploy to development
   jobs:
   - job: DeployJob
     steps:
     - script: echo 'hello, world'
       displayName: 'Run script'
-- stage: production
+- stage: Production
   displayName: Deploy to production
   trigger: manual
   jobs:
@@ -389,9 +405,9 @@ stages:
 
 ## Mark a stage as unskippable
 
-Mark a stage as `isSkippable: false` to prevent pipeline users from skipping stages. For example, you may have a YAML template that injects a stage that performs malware detection in all pipelines. If you set `isSkippable: false` for this stage, Pipeline won't be able to skip malware detection.
+Mark a stage as `isSkippable: false` to prevent pipeline users from skipping stages. For example, you might have a YAML template that injects a stage that performs malware detection in all pipelines. If you set `isSkippable: false` for this stage, your pipeline won't be able to skip malware detection.
 
-In the following example, the Malware detection stage is marked as non-skippable, meaning it must be executed as part of the pipeline run. 
+In the following example, the Malware detection stage is marked as nonskippable, meaning it must be executed as part of the pipeline run. 
 
 ```yaml
 - stage: malware_detection
@@ -402,7 +418,7 @@ In the following example, the Malware detection stage is marked as non-skippable
     ...
 ```
 
-When a stage is non-skippable, it will show with a disabled checkbox in the **Stages to run** configuration panel.
+When a stage is nonskippable, it shows with a disabled checkbox in the **Stages to run** configuration panel.
 
 :::image type="content" source="media/stages/stages-run-skip-stage.png" alt-text="Screenshot of stages to run with disabled stage. ":::