Merge pull request #8059 from MicrosoftDocs/pipelines/437466

Classic to YAML pipelines

Author: denrea

docs/pipelines/release/from-classic-pipelines.md

@@ -1,110 +1,79 @@
 ---
-title: Migrate from Classic to YAML pipelines
+title: Migrate your Classic pipeline to YAML
 titleSuffix: Azure Pipelines
-description: How to migrate from Classic pipelines to YAML.
+description: Learn how to migrate from Classic pipelines to YAML.
 ms.subservice: azure-devops-pipelines-migrate
 ms.topic: quickstart
-ms.date: 07/01/2024
+ms.date: 06/26/2025
 monikerRange: azure-devops
 ---
 
 # Migrate your Classic pipeline to YAML
 
 [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)]
 
-Get started with Azure Pipelines by converting your existing Classic pipeline to use YAML. With a YAML-based pipeline, you can implement your CI/CD strategy as code and see its history, compare versions, blame, annotate, and so on.
+Azure Pipelines lets you manage your CI/CD process as code, making it easier to track changes, compare versions, annotate, and more.
 
-When you convert your Classic pipeline, the end product is two pipelines. You'll have one new YAML pipeline and a Classic pipeline that can be retired. Your Classic pipeline's run history remains in the Classic pipeline. 
+When you convert a Classic pipeline, you’ll end up with two pipelines: a new YAML pipeline and the original Classic one, which can then be retired. Your Classic pipeline's run history remains in the Classic pipeline. 
 
 > [!NOTE]
-> You can only export a YAML file from an existing Classic pipeline created with the classic build designer. If you don't see the option to export to JSON or YAML, then your pipeline doesn't support exporting. Classic release pipelines don't have the export to YAML option. You can export a classic release pipeline by exporting each individual task. 
+> You can only export a YAML file from a Classic pipeline created using the classic build designer. If you don’t see an option to export to YAML or JSON, your pipeline likely doesn’t support exporting. Classic release pipelines don’t support YAML export, you’ll need to export each task individually. 
 
 ## Prerequisites
 
-Make sure you have the following items before you begin.
-
-- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
-- An active Azure DevOps organization. [Sign up for Azure Pipelines](../get-started/pipelines-sign-up.md).
-- A working pipeline that uses the Classic user interface (UI) editor.
-- A sample YAML pipeline file in your code. Create a sample YAML pipeline in the following section.
+| **Product**        | **Requirements**   |
+|--------------------|--------------------|
+| **Azure**   | - An Azure account with an active [subscription](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). |
+| **Azure DevOps**   | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).<br>- An Azure DevOps [project](../../organizations/projects/create-project.md).<br> - Allow [Azure Artifacts Domain URLs and IP addresses](../../organizations/security/allow-list-ip-url.md) if your organization is using a firewall or a proxy server.<br> - A working Classic pipeline.  |
 
 ## Create a sample YAML pipeline
 
-Do the following steps to create a sample YAML pipeline, which you'll update later with your exported code from the Classic UI editor.
-
-1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) and select your project.
-
-2. Select **Pipelines**, and then **New pipeline**.
-
-   :::image type="content" source="media/pipelines-new-pipeline.png" alt-text="Two buttons to select for new pipeline creation.":::
+Follow these steps to create a starter YAML pipeline, which you’ll later update with code exported from the Classic UI editor:
 
-3. Select the location for your source code as either **GitHub** or **Azure Repos Git**.
+1. Sign in to your organization, and navigate to your project.
 
-   :::image type="content" source="media/source-code-location.png" alt-text="List of possible selections for your source code.":::
+1. Select **Pipelines**, and then select **New pipeline**.
 
-4. Select a repository.
+   :::image type="content" source="media/pipelines-new-pipeline.png" alt-text="A screenshot displaying how to create a new pipeline.":::
 
-   :::image type="content" source="media/select-repository.png" alt-text="Page where you select a repository for your source code pipeline.":::
+1. Select your source code location either **GitHub** or **Azure Repos Git**, and then select your repository.
 
-5. On the Configure your pipeline page, select **Starter pipeline**.
+   :::image type="content" source="media/source-code-location.png" alt-text="A screenshot displaying source code locations.":::
 
-   :::image type="content" source="media/select-pipeline-template.png" alt-text="List of templates to choose from for configuring your new pipeline.":::
+1. On the **Configure your pipeline page**, select the **Starter pipeline**.
 
-6. Select **Save and run**.
+   :::image type="content" source="media/select-pipeline-template.png" alt-text="A screenshot displaying the available pipeline templates.":::
 
-   :::image type="content" source="media/save-run-new-yaml-pipeline.png" alt-text="Review page where you select Save and run.":::
+1. Select **Save and run**, and then enter your commit message. Select **Commit directly to the main branch**, and then select **Save and run** once more. This will start a new run and commit the yaml pipeline to your repository.
 
-7. Enter your commit message, select **Commit directly to the main branch**, and then choose **Save and run** again. A new run starts and it's committed to the repository. Wait for the run to finish.
+   :::image type="content" source="media/commit-save-run.png" alt-text="A screenshot displaying how to save and run a new yaml pipeline.":::
 
-   :::image type="content" source="media/commit-save-run.png" alt-text="Commit message to commit to the main branch, and then select Save and run button.":::
+## Export a Classic pipeline to YAML
 
-## Export your Classic pipeline
-
-1. Sign in to your Azure DevOps organization, and then go to your project.
+1. Sign in to your Azure DevOps organization, and navigate to your project.
 
 1. Select **Pipelines** > **Pipelines**. 
 
-1. Select your Classic pipeline definition, select the ellipses icon, and then select **Export to YAML**. Make sure you're in the pipeline definition view, not a specific run, to see the **Export to YAML** option.
+1. Find your Classic pipeline, select the ellipses (...) next to it, and then select **Export to YAML**. Make sure you're in the pipeline definition view, not a specific run, to see the **Export to YAML** option.
 
-    :::image type="content" source="media/export-yaml.png" alt-text="Screenshot of context menu, to export your pipeline to YAML.":::
+    :::image type="content" source="media/export-yaml.png" alt-text="A screenshot displaying how to export a Classic pipeline to YAML.":::
 
 1. Open the downloaded YAML file in your code editor.
 
-1. If your YAML pipeline includes variables defined in the Classic UI, define the variables again in your pipeline settings UI or in your YAML file. For more information, see [Define variables](../process/variables.md).
-
-1. Review any `cron` schedules in your YAML file. By default, `cron` schedules in YAML are in UTC. In Classic pipelines, they are in the organization's timezone. For more information, see [Configure schedules for pipelines](../process/scheduled-triggers.md).
-
-1. Use the Task Assistant to make any other changes to the YAML file. The Task Assistant is a pane on the right side of the screen, which helps you correctly create and modify YAML steps.
-
-    :::image type="content" source="media/task-assistant-yaml.png" alt-text="Configure your pipeline task with Task Assistant.":::
+1. If your Classic pipeline used variables defined in the Classic UI editor, you’ll need to redefine them either in the YAML file or in the pipeline settings. See [Define variables](../process/variables.md) for more details.
 
-1. **Save and run** your pipeline.
+1. Review any `cron` schedules in your YAML file. YAML schedules use UTC by default, while Classic pipelines use your organization’s local time zone. See [Configure schedules for pipelines](../process/scheduled-triggers.md) for more details.
 
-## Clean up resources
+1. Use the **Task Assistant** (the pane on the right side of the editor) to help you add or modify steps in your YAML file.
 
-If you're not going to use this sample pipeline anymore, delete it from your project. Deletion is permanent and includes all builds and associated artifacts.
+    :::image type="content" source="media/task-assistant-yaml.png" alt-text="A screenshot displaying how to configure pipeline tasks with the Task Assistant.":::
 
-1. Select the ellipses (...) and select **Delete**.
+1. Select **Save and run** once you're done.
 
-2. Enter the name of your pipeline to permanently delete it, and then select **Delete**.
+## Related content
 
-## FAQ
-
-### Is there a task in YAML pipelines to create work items when there's a build failure? 
-
-YAML pipelines don't have a [Create work item on failure setting](../build/options.md#create-a-work-item-on-failure) like classic build pipelines. You have a couple of options for creating this functionality yourself.
-- You can use a script or PowerShell task and call the [REST API](/rest/api/azure/devops/pipelines/). 
-- You can use Azure CLI to call [az boards work-item create](/cli/azure/boards/work-item#az-boards-work-item-create) in your pipeline. [See an example](../customize-pipeline.md#create-work-item-on-failure) of using the CLI to create a bug on failure.
-
-## Next steps
-
-Learn about the feature differences between YAML and Classic pipelines.
-
-> [!div class="nextstepaction"]
-> [Use Azure Pipelines](../get-started/pipelines-get-started.md#feature-availability)
-
-## Related articles
+- [YAML vs Classic Pipelines](../get-started/pipelines-get-started.md#feature-availability)
 
 - [Customize your pipeline](../customize-pipeline.md)
-- [Learn YAML pipeline editor basics](../get-started/yaml-pipeline-editor.md)
-- [Define approvals and checks](../release/approvals/approvals.md)
+
+- [YAML pipeline editor](../get-started/yaml-pipeline-editor.md)

docs/pipelines/toc.yml

@@ -720,7 +720,7 @@
     href: release/approvals/servicenow.md
 - name: Migrate
   items:
-  - name: Migrate from Classic pipelines
+  - name: Migrate Classic pipelines to YAML 
     href: release/from-classic-pipelines.md
   - name: Migrate from Jenkins
     href: migrate/from-jenkins.md