NEW: Migrate your CI/CD Pipelines to GitHub with GitHub Actions Importer

github/migrate-cicd-pipelines-to-github-with-github-actions-importer/1-introduction.yml

@@ -0,0 +1,14 @@
+### YamlMime:ModuleUnit
+uid: learn.migrate-cicd-pipelines-to-github-with-github-actions-importer.introduction
+title: Introduction
+metadata:
+  title: introduction
+  description: "Learn about GitHub Actions Importer and how it can help facilitate migrations from your current CI/CD tool to GitHub Actions."
+  ms.date: 1/10/2023
+  author: a-a-ron
+  ms.author: aastewar
+  ms.topic: interactive-tutorial
+  ms.prod: learning-azure # Edit as appropriate for your portfolio area
+durationInMinutes: 1
+content: |
+  [!include[](includes/1-introduction.md)]

github/migrate-cicd-pipelines-to-github-with-github-actions-importer/2-Learn-about-the-two-distinct-phases-of-a-GitHub-Actions-Importer-migration-and-their-associated-commands.yml

@@ -0,0 +1,14 @@
+### YamlMime:ModuleUnit
+uid: learn.migrate-cicd-pipelines-to-github-with-github-actions-importer.exercise
+title: How-execute-GitHub-Actions-Importer-commands-and-what-is-not-automatically-migrated
+metadata:
+  title: exercise
+  description: Understand the GitHub Actions Importer commands: audit, forecast, dry-run, and migrate as well as learn what is not automatically migrated
+  ms.date: 1/10/2023
+  author: a-a-ron
+  ms.author: aastewar
+  ms.topic: interactive-tutorial
+  ms.prod: learning-azure # Edit as appropriate for your portfolio area
+durationInMinutes: 10
+content: |
+  [!include[](includes/How-execute-GitHub-Actions-Importer-commands-and-what-is-not-automatically-migrated..md)]

github/migrate-cicd-pipelines-to-github-with-github-actions-importer/3-exercise.yml

@@ -0,0 +1,14 @@
+### YamlMime:ModuleUnit
+uid: learn.migrate-cicd-pipelines-to-github-with-github-actions-importer.exercise
+title: GitHub Actions Importer Labs
+metadata:
+  title: exercise
+  description: GitHub Actions Importer helps plan, forecast, and automate the migration of Azure DevOps, CircleCI, GitLab, Jenkins, and Travis CI pipelines to GitHub Actions. This repository contains learning paths that teach you how to use GitHub Actions Importer and how to approach migrations to Actions.
+  ms.date: 1/10/2023
+  author: a-a-ron
+  ms.author: aastewar
+  ms.topic: interactive-tutorial
+  ms.prod: learning-azure # Edit as appropriate for your portfolio area
+durationInMinutes: 1
+content: |
+  [!include[](includes/5-exercise.md)]

github/migrate-cicd-pipelines-to-github-with-github-actions-importer/4-knowledge-check.yml

@@ -0,0 +1,63 @@
+### YamlMime:ModuleUnit
+uid: learn.migrate-cicd-pipelines-to-github-with-github-actions-importer.knowledge-check
+title: Knowledge check
+metadata:
+  title: Knowledge check
+  description: "Test your knowledge on GitHub Actions Importer with questions about its commands and supported CI platforms."
+  ms.date: 1/10/2023
+  author: a-a-ron
+  ms.author: aastewar
+  ms.topic: interactive-tutorial
+  ms.prod: learning-azure 
+durationInMinutes: 5
+content: |
+quiz:
+  questions:
+  - content: "Which of the following are supported in a GitHub Actions Importer migration?"
+    choices:
+    - content: "Widely used build steps and triggers"
+      isCorrect: true
+      explanation: "Correct! Widely used build steps and tiggers are included in GitHub Actions Importer migrations. What you want to be wary of is less frequently used build steps and triggers."
+    - content: "Secrets and encrypted values"
+      isCorrect: false
+      explanation: "Secrets and encrypted values are not included in GitHub Actions Importer migrations."
+    - content: "Self-hosted build agents"
+      isCorrect: false
+      explanation: "Self-hosted build agents are not included in GitHub Actions Importer migrations."
+    - content: "Historical packages"
+      isCorrect: false
+      explanation: "Historical packages are not included in GitHub Actions Importer migrations."
+    - content: "Permissions for CI/CD pipelines"
+      isCorrect: false
+      explanation: "Permissions for CI/CD pipelines are not included in GitHub Actions Importer migrations."
+  - content: "Which of the following is *NOT* part of the Audit summary?"
+    choices:
+    - content: "Pipelines"
+      isCorrect: false
+      explanation: "Pipelines are included in the Audit summary."
+    - content: "Templates"
+      isCorrect: true
+      explanation: "Correct! Templates are NOT a part of the Audit summary."
+    - content: "Build steps"
+      isCorrect: false
+      explanation: "Build steps are included in the Audit summary."
+    - content: "Manual tasks"
+      isCorrect: false
+      explanation: "Manual tasks are included in the Audit summary."
+    - content: "File manifest"
+      isCorrect: false
+      explanation: "The File manifest is included in the Audit summary."
+  - content: "Which of the following metrics are *NOT* included in the Forecast report?"
+    choices:
+    - content: "Execution time"
+      isCorrect: false
+      explanation: "Execute time is part of a Forecast report."
+    - content: "Queue time"
+      isCorrect: false
+      explanation: "Queue time is part of a Forecast report."
+    - content: "Pipeline count"
+      isCorrect: false
+      explanation: "Pipeline count is part of a Forecast report."
+    - content: "Total CI/CD spend"
+      isCorrect: true
+      explanation: "Correct! Total CI/CD spend is NOT part of a Forecast report."

github/migrate-cicd-pipelines-to-github-with-github-actions-importer/5-summary.yml

@@ -0,0 +1,14 @@
+### YamlMime:ModuleUnit
+uid: learn.migrate-cicd-pipelines-to-github-with-github-actions-importer.summary
+title: Summary
+metadata:
+  title: Summary
+  description: Through this module you should have learned how to install and update GitHub Actions Importer as well as learn about its four commands and what is not automatically mirgrated. 
+  ms.date: 1/10/2023
+  author: a-a-ron
+  ms.author: aastewar
+  ms.topic: interactive-tutorial
+  ms.prod: learning-azure # Edit as appropriate for your portfolio area
+durationInMinutes: 1
+content: |
+  [!include[](includes/7-summary.md)]

github/migrate-cicd-pipelines-to-github-with-github-actions-importer/includes/1-introduction.md

@@ -0,0 +1,42 @@
+GitHub Actions Importer is designed to help you forecast, plan, and facilitate migrations from your current CI/CD tool to GitHub Actions. 
+
+Doing individual migrations is relatively easy in isolation. However, if you have a large and established CI/CD footprint, having a tool capable to assist with migrations is key to your ability to adopt GitHub Actions at scale.
+
+## Learning objectives
+
+In this module you will:
+
+- Learn about the two distinct phases of a GitHub Actions Importer migration and the phases' associated commands
+- Run through a mock migration lab exercise for one of the supported CI/CD platforms listed below
+
+## Prerequisites
+
+- A GitHub account
+- Prior working knowledge of GitHub Actions
+- Organizational access to one of the supported CI/CD platforms below 
+
+## Important notes
+
+As you'll learn from this module, you can use GitHub Actions Importer to plan and automatically migrate your CI/CD pipelines to GitHub Actions from the following supported platforms: 
+
+- Azure DevOps
+- CircleCI
+- GitLab
+- Jenkins
+- Travis CI
+
+It is imperative to review every workflow that is converted by the GitHub Actions Importer for correctness before using it as a production workload. 
+
+The goal is to achieve an 80% conversion rate for every workflow, but like all things, the actual conversion rate will depend on your specific makeup of your pipelines. 
+
+To set expectations, it is important to note that there are a couple of things that won't be automatically migrated when you use GitHub Actions Importer.
+
+#### What is *not* automatically migrated:
+
+- Secrets and encrypted values 
+- Self-hosted build agents
+- Historical packages
+- Permissions for CI/CD pipelines
+- Less commonly used build steps or build triggers
+
+Now, let's dive into how to install GitHub Actions Importer and ensure it is up to date. 

github/migrate-cicd-pipelines-to-github-with-github-actions-importer/includes/2-Learn-about-the-three-distinct-phases-of-a-GitHub-Actions-Importer-migration-and-their-associated-commands.md

@@ -0,0 +1,146 @@
+In the following lab exericse you will be provided step-by-step guidelines on how to run all four commands for each of the supported CI/CD platforms. 
+
+But in the meantime, in this unit we will be reviewing the three phases of a GitHub Actions Importer Migration: **planning, testing,** and **migrating** and their associated commands.
+
+- We’ll walk through the **planning phase** of your migration and introduce you to the:
+  - The ```audit```
+  - And the ```forecast``` commands
+- Then we'll introduce you to the **testing phase**, which includes
+  - The ```dry-run``` command
+  - As well as custom transformers
+- And for the **migration phase**, we’ll introduce you to the ```migration``` command.
+- And we will round things out with a review of what is not automatically migrated over with GitHub Actions Importer. 
+
+But for now, let’s start with the planning phase of your migration.
+
+## The planning phase
+
+The planning phase of a migration typically starts with an analysis of your existing CI/CD usage and approach, which includes addressing such questions as:
+
+- How many pipelines are currently defined?
+- What is the typical makeup of these pipelines? Are they defined using out-of-the-box tasks, or is the product being extended to - provide custom behavior?
+- Which pipelines are the highest priority to be migrated? Should any pipelines not be migrated?
+- What type and how many runners are being used? What mix of GitHub-hosted and self-hosted runners should you select when migrating?
+
+If you find yourself leaving these questions unanswered, fear not, GitHub Actions Importer can help you find out your answers to these questions with its commands. 
+
+Let's get started with getting to know the ```audit``` command. 
+
+### What is the audit command?
+In this section we’ll be going over the basics of the ```audit``` command with GitHub Actions Importer.
+
+The ```audit``` command does the following: 
+- Fetches all of the pipelines defined in a specified scope of the existing CI/CD environment
+- Attempts a conversion of these pipelines to their equivalent Actions workflow 
+- Writes a summary report with statistics gathered from the audit 
+
+The ```audit``` command is designed to help analyze the complexity of a potential migration, which can be used to formulate a migration plan. 
+
+Running an audit on the command line will look something like this:
+```
+$ gh actions-importer audit jenkins --output-dir 
+```
+
+Once you initiate the command it will provide an Audit summary report.
+
+Let’s go over the details the Audit summary report will provide you. 
+
+#### What is in an Audit summary report?
+
+There are four sections of the Audit summary: 
+
+- **Pipelines:** This section contains high-level aggregated statistics on GitHub Actions Importer’s ability to migrate the targeted pipeline automatically.
+- **Build steps:** This section presents an aggregated summary of the individual build steps that are used across all of the target pipelines and how many could be converted automatically.
+- **Manual tasks:** This section presents an overview of the manual tasks that can be identified.
+- **File manifest:** The final section of the audit summary report provides a manifest of all the files generated during the audit. 
+
+:::image type="content" source="../media/Audit_summary.jpg" alt-text="Audit summary for an Jenkins instance with sections of Pipelines and Job types.":::
+
+Next, let's get into the ```forecast``` command. 
+
+### What is the forecast command?
+
+In this section we’ll be reviewing the ```forecast``` command and walking through a Forecast report. 
+
+The ```forecast``` command fetches jobs that have been completed over a specified time period and uses that data to calculate usage metrics.
+
+Running a forecast on the command line will look something like the image below. 
+
+:::image type="content" source="../media/Forecast_report.jpg" alt-text="Forecast report for Jenkins with Job count, Pipeline count, Execution time, Queue time, and Concurrent jobs sections.":::
+
+
+#### What is in a Forecast report?
+
+The Forecast report includes these metrics:
+
+- **Job count:** The total number of completed jobs.
+- **Pipeline count:** The number of unique pipelines used.
+- **Execution time:** The amount of time a runner spent on a job. This metric can be used to help set expectations for the cost of GitHub-hosted runners.
+- **Queue time:** The amount of time a job spent waiting for a runner to be available.
+- **Concurrent jobs:** The number of jobs running at any given time. This metric can be used to understand the number of concurrent runners necessary at current levels.
+
+Additionally, these metrics are presented for each runner queue defined in the source CI/CD system. This is useful if you will need a mix of hosted and self-hosted runners and/or if you use a mix of platforms.
+
+In the next section, we’ll be diving into the ```dry-run``` command. 
+
+## The testing phase
+
+The testing phase of a GitHub Actions Importer migration allows you test run what your mirgration will look like. 
+
+By using the ```dry-run``` command you can see what might not be automatically converted and utilize custom transformers to convert items into your new GitHub environment. 
+
+Let's first review the ```dry-run``` command.
+
+### What is the dry-run command?
+
+In this section we will review what the ```dry-run``` command does. 
+
+You can use the ```dry-run``` command to convert an existing pipeline to its equivalent GitHub Actions workflow. 
+
+The console output of the command will list the path to the file or files that GitHub Actions Importer generated. Before migrating, you should perform a dry-run of a pipeline and validate the contents are suitable.
+
+If the conversion of a pipeline was only “partially successful” (that is, it included tasks that could not be converted automatically), the task that was not converted will be included in a commented section.
+
+If you have "partially successful" items you can utilize custom transformers to extend GitHub Actions Importer's mapping logic. 
+
+Let's touch upon custom transformers in our next section.
+
+### Custom transformers
+
+A custom transformer contains mapping logic that GitHub Actions Importer can use to transform your plugins, tasks, runner labels, or environment variables to work with GitHub Actions.
+
+Custom transformers can be used to:
+- Convert items that GitHub Actions Importer does not automatically convert, or modify how items are converted.
+- Convert references to runners to use different runner labels. 
+- Convert environment variable values from your existing pipelines to GitHub Actions workflows.
+
+Once you have built custom transformers for your items that needed to be converted into your new environment, the next step is to finally migrate.
+
+Next up, we'll be tackling how to migrate your environment. 
+
+## The migration phase
+
+You can use the ```migrate``` command to convert an existing pipeline to its equivalent action and open a pull request with the converted workflows and associated files.
+
+```
+$ gh actions-importer migrate jenkins --source-url $SOURCE_URL –target-url $TARGET_URL --output-dir 
+```
+
+Any necessary manual tasks will be included in the description of the pull request. Once these manual tasks and the code reviews are complete, the pull request can be merged and the workflow will have been successfully migrated to GitHub Actions.
+
+:::image type="content" source="../media/PR_for_Migration.jpg" alt-text="New PR once a migration is completed.":::
+
+Now, let’s take a moment to review and dive a bit deeper into what is not automatically migrated with GitHub Actions Importer. 
+
+### Understand what is not migrated automatically
+
+GitHub Actions Importer cannot migrate everything. It’s important to be mindful of its limitations, which include:
+
+- **Secrets and encrypted values** are not automatically converted to repository secrets. References to secrets will be converted into context expressions and populating these values will be a manual task.
+- **Self-hosted build agents** are not automatically converted to self-hosted runners. Determining whether to use GitHub-hosted runners or create equivalent self-hosted runners will be a manual task. References to these self-hosted runners will be converted to the same set of labels in a ```needs``` statement in the resulting workflow.
+- **Historical packages** are not migrated to GitHub Packages. Any steps that publish or consume pipeline artifacts and caches will be converted using the equivalent actions.
+- **Permissions for CI/CD pipelines** are not migrated automatically and will need to be manually configured.
+- **Build steps or build triggers** that are less commonly used may not be automatically converted by GitHub Actions Importer. This can be a factor for migrations involving Azure DevOps, Jenkins, and CircleCI, all of which can be extended through marketplace customizations.
+
+
+Like we had mentioned earlier, the upcoming [lab exercise](https://github.com/actions/importer-labs) will provide step-by-step guidelines on how to run all four commands for each of the supported CI/CD platforms. Let's go there next!

github/migrate-cicd-pipelines-to-github-with-github-actions-importer/includes/3-exercise.md

@@ -0,0 +1,17 @@
+This exercise will walk you through how to utilize the four GitHub Action Importer commands within one of the supported CI/CD platforms.
+
+## Getting started
+
+When you click the _Start the exercise on GitHub_ button below, you'll be navigated to a public GitHub template repository that will prompt you to complete a series of small challenges. Before you can begin the exercise, complete the below tasks:
+
+- Follow the instructions in the repository's README to understand how the exercise works and select your preferred CI/CD platform you would like to utilize.
+
+When you've finished the exercise in GitHub, return here for:
+
+> [!div class="checklist"]
+> * A quick knowledge check 
+> * A summary of what you've learned
+> * To earn a badge for completing this module
+
+> [!div class="nextstepaction"]
+> [Start the exercise on GitHub](https://github.com/actions/importer-labs)

github/migrate-cicd-pipelines-to-github-with-github-actions-importer/includes/5-summary.md

@@ -0,0 +1,15 @@
+In this module you learned about GitHub Actions Importer, how to ensure it is up to date, its supported CI/CD platforms, the commands you can run on it, and what might not be migrated automatically from your previous CI/CD environment.
+
+You learned about:
+- Learn about the two distinct phases of a GitHub Actions Importer migration and the phases' associated commands
+- Run through a mock migration lab exercise for one of the supported CI/CD platforms listed below
+
+## Learn more
+
+Here are some links to more information on the topics we discussed in this module:
+- [Automating migration with GitHub Actions Importer](https://docs.github.com/en/actions/migrating-to-github-actions/automating-migration-with-github-actions-importer)
+- [GitHub Actions Importer labs](https://github.com/actions/importer-labs/tree/main#readme)
+
+## How to provide feedback ✍️
+
+If you have content feedback or suggested changes for a Microsoft Learn module, please use the [MS Learn Module Update Request](https://github.com/githubpartners/microsoft-learn/issues/new/choose) issue form to provide that feedback and a team member will triage the request. Thank you for taking the time to improve our content!