actions/importer-labs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'main' into JenniferKerns-patch-14

Browse Source
This commit is contained in:
Ethan Dennis
2022-11-06 18:02:53 -08:00
committed by GitHub
parent 6ff2e73b30 56baee6a36
commit f39d65d1ca
12 changed files with 65 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
azure_devops/1-configure.md
+1 -1
View File
@@ -66,7 +66,7 @@ You will need to complete all of the setup instructions [here](./readme.md#confi
## Verify your environment
To verify our environment is configured correctly, run the `update` CLI command. The `update` CLI command will download the latest version of GitHub Actions Importer to your codespace.
To verify your environment is configured correctly, run the `update` CLI command. The `update` CLI command will download the latest version of GitHub Actions Importer to your codespace.
1. In the codespace terminal, run the following command:
azure_devops/2-audit.md
+4 -4
View File
@@ -69,7 +69,7 @@ Supported: **5 (100%)**
- YAML: **3**
```
Here are some key terms in the "Pipelines" section in the above example:
Here are some key terms in the "Pipelines" section:
- __Successful__ pipelines had 100% of the pipeline constructs and individual items converted automatically to their GitHub Actions equivalent.
- __Partially successful__ pipelines had all of the pipeline constructs converted, however, there were some individual items (e.g. build tasks or build triggers) that were not converted automatically to their GitHub Actions equivalent.
@@ -111,7 +111,7 @@ Actions: **19**
- actions/setup-node@v2: **1**
```
Here are some key terms in the "Build steps" section in the above example:
Here are some key terms in the "Build steps" section:
- A __known__ build step is a step that was automatically converted to an equivalent action.
- An __unknown__ build step is a step that was not automatically converted to an equivalent action.
@@ -138,7 +138,7 @@ Self hosted runners: **1**
- `mechamachine`: **1**
```
Here are some key terms in the "Manual tasks" section in the above example:
Here are some key terms in the "Manual tasks" section:
- A __secret__ refers to a repository or organization level secret that is used by the converted pipelines. These secrets will need to be created manually in Actions in order for these pipelines to function properly.
- A __self-hosted runner__ refers to a label of a runner that is referenced by a converted pipeline that is not a GitHub-hosted runner. You will need to manually define these runners in order for these pipelines to function properly.
@@ -176,7 +176,7 @@ Each pipeline will have a variety of files written that include:
- The converted workflow.
- Stack traces that can used to troubleshoot a failed pipeline conversion
## Inspect the workflow usage csv file
## Inspect the workflow usage .csv file
1. Open the `tmp/audit/workflow_usage.csv` file in the file explorer.
2. This file contains a comma-separated list of all actions, secrets, and runners that are used by each successfully converted pipeline:
azure_devops/5-custom-transformers.md
+2 -2
View File
@@ -112,7 +112,7 @@ end
The `transform` method can use any valid ruby syntax and should return a `Hash` that represents the YAML that should be generated for a given step. GitHub Actions Importer will use this method to convert a step with the provided identifier and will use the `item` parameter for the original values configured in Azure DevOps.
Now, we can perform a `dry-run` command with the `--custom-transformers` CLI option. The output of the `dry-run` command should look similar to this:
Now, you can perform a `dry-run` command with the `--custom-transformers` CLI option. The output of the `dry-run` command should look similar to this:
```console
$ gh actions-importer dry-run azure-devops pipeline --pipeline-id 6 --output-dir tmp/dry-run --custom-transformers transformers.rb
@@ -153,7 +153,7 @@ Now you can perform another `dry-run` command and use the `--custom-transformers
gh actions-importer dry-run azure-devops pipeline --pipeline-id :pipeline_id --output-dir tmp/dry-run --custom-transformers transformers.rb
```
Open the workflow that is generated and inspect the contents. Now the `DotnetCoreCLI@2` steps are converted using the customized behavior!
Open the workflow that is generated and inspect the contents. The `DotnetCoreCLI@2` steps are now converted using the customized behavior.
```diff
- - name: Restore
azure_devops/6-migrate.md
+6 -6
View File
@@ -12,11 +12,11 @@ In this lab, you will use the `migrate` command to convert an Azure DevOps pipel
Answer the following questions before running a `migrate` command:
1. What is the id of the pipeline to convert?
- __:pipeline_id__. This id can be found by:
1. What is the ID of the pipeline to convert?
- __:pipeline_id__. This ID can be found by:
- Navigating to the build pipelines in the bootstrapped Azure DevOps project <https://dev.azure.com/:organization/:project/_build>
- Selecting the pipeline with the name "pipeline2"
- Inspecting the URL to locate the pipeline id <https://dev.azure.com/:organization/:project/_build?definitionId=:pipeline_id>
- Inspecting the URL to locate the pipeline ID <https://dev.azure.com/:organization/:project/_build?definitionId=:pipeline_id>
2. Where do you want to store the logs?
- __tmp/migrate__
3. What is the URL for the GitHub repository to add the workflow to?
@@ -30,7 +30,7 @@ Answer the following questions before running a `migrate` command:
gh actions-importer migrate azure-devops pipeline --pipeline-id :pipeline_id --target-url https://github.com/:owner/:repo --output-dir tmp/migrate
```
2. The command will write the URL to the pull request that was created when the command succeeds.
2. The command will write the URL to the pull request that is created when the command succeeds.
```console
$ gh actions-importer migrate azure-devops pipeline --pipeline-id 8 --target-url https://github.com/ethanis/labs --output-dir tmp/migrate
@@ -52,8 +52,8 @@ Finally, you can merge the pull request once your review has completed. You can
![img](https://user-images.githubusercontent.com/19557880/185509704-90243ec5-e77f-4baf-a9b2-d9a4d9fda199.png)
At this point, the migration has completed and you have successfully migrated an Azure DevOps pipeline to Actions!
At this point, the migration has completed and you have successfully migrated an Azure DevOps pipeline to Actions.
### Next lab
This concludes all labs for migrating Azure DevOps pipelines to Actions with GitHub Actions Importer!
This concludes all labs for migrating Azure DevOps pipelines to Actions with GitHub Actions Importer.
azure_devops/readme.md
+4 -7
View File
@@ -1,6 +1,6 @@
# Azure Pipelines to Actions migrations powered by GitHub Actions Importer
# Azure Pipelines migrations powered by GitHub Actions Importer
These instructions will guide you through configuring the GitHub Codespaces environment that will be used in these labs to demonstrate how to use GitHub Actions Importer to migrate Azure DevOps pipelines to GitHub Actions.
These instructions will guide you through configuring the GitHub Codespaces environment that you will use in these labs to learn how to use GitHub Actions Importer to migrate Azure DevOps pipelines to GitHub Actions.
These steps **must** be completed prior to starting other labs.
@@ -34,7 +34,7 @@ These steps **must** be completed prior to starting other labs.
actions-importer/cli unknown
```
- If `gh actions-importer version` did not produce similar output, please refer to the troubleshooting [guide](#troubleshoot-the-actions-importer/cli).
- If `gh actions-importer version` did not produce similar output, please refer to the [troubleshooting section](#troubleshoot-the-github-actions-importer-cli).
## Bootstrap your Azure DevOps organization
@@ -45,7 +45,7 @@ These steps **must** be completed prior to starting other labs.
- Click `Personal access tokens`.
- Select `+ New Token`
- Name your token, select the organization where you want to use the token, and set your token to automatically expire after a set number of days.
- Select the following scopes (you may need to `Show all scopes` at the bottom of the page to reveal all scopes):
- Select the following scopes (you may need to select `Show all scopes` at the bottom of the page to reveal all scopes):
- Agents Pool: `Read`
- Build: `Read & execute`
- Code: `Read & write`
@@ -101,9 +101,6 @@ The CLI extension for GitHub Actions Importer can be manually installed by follo
✓ Installed extension github/gh-actions-importer
```
- If you get an error similar to the image below, click the link in the terminal output to authorize the token.
- Restart the codespace after clicking the link.
![img](https://user-images.githubusercontent.com/26442605/169588015-9414404f-82b6-4d0f-89d4-5f0e6941b029.png)
- Verify GitHub Actions Importer CLI extension is installed and working by running the following command from the codespace terminal:
```bash
circle_ci/1-configure.md
+20 -20
View File
@@ -6,29 +6,29 @@ You will need to complete all of the setup instructions [here](./readme.md#confi
## Configuring credentials
1. Create a GitHub Personal Access Token (PAT):
- Open github.com in a new browser tab.
- Click your profile photo in the top right of the UI and click `Settings`.
- Click on `Developer Settings` in the left hand panel.
- Click `Personal Access Tokens` and then `Legacy tokens` (if present).
- Click `Generate new token` and then `Legacy tokens`. You may be required to authenticate with GitHub during this step.
- Select the following scopes: `read:packages` and `workflow`.
- Click `Generate token`.
- Copy the generated PAT and save in a safe location.
1. Create a GitHub personal access token (PAT):
- Open github.com in a new browser tab.
- In the top right of the UI, click your profile photo and then click `Settings`.
- In the left panel, click `Developer Settings`.
- Click `Personal access tokens` and then `Tokens (classic)` (if present).
- Click `Generate new token` and then `Generate new token (classic)`. You may be required to authenticate with GitHub during this step.
- Select the following scopes: `read:packages` and `workflow`.
- Click `Generate token`.
- Copy the generated PAT and save in a safe location.
3. Create a CircleCI personal API token using CircleCI's [documentation](https://circleci.com/docs/managing-api-tokens#creating-a-personal-api-token) and store the token in a safe location.
2. Run the `configure` CLI command:
- Select the `TERMINAL` tab from within the codespace terminal window.
- Run the following command: `gh actions-importer configure`.
- Using the down arrow key to highlight `CircleCI`, press the spacebar to select, and then hit enter to continue.
- At the GitHub handle prompt, enter the GitHub username used to generate the GitHub PAT in step 2 and press enter.
- At the GitHub Container Registry prompt, enter the GitHub PAT generated in step 1 and press enter.
- At the GitHub PAT prompt, enter the GitHub PAT generated in step 1 and press enter.
- At the GitHub url prompt, enter the GitHub instance url or hit enter to accept the default value (`https://github.com`).
- At the CircleCI token prompt, enter the CircleCI access token from step 2 and press enter.
- At the CircleCI base url prompt, hit enter to accept the default value (`https://circleci.com`).
- At the CircleCI organization name prompt, enter `actions-importer-labs`. This is the organization we'll be using throughout these labs.
- Select the `TERMINAL` tab from within the codespace terminal window.
- Run the following command: `gh actions-importer configure`.
- Using the down arrow key to highlight `CircleCI`, press the spacebar to select, and then press enter to continue.
- At the GitHub handle prompt, enter the GitHub username used to generate the GitHub PAT in step 2 and press enter.
- At the GitHub Container Registry prompt, enter the GitHub PAT generated in step 1 and press enter.
- At the GitHub PAT prompt, enter the GitHub PAT generated in step 1 and press enter.
- At the GitHub URL prompt, enter the GitHub instance URL or press enter to accept the default value (`https://github.com`).
- At the CircleCI token prompt, enter the CircleCI access token from step 2 and press enter.
- At the CircleCI base URL prompt, press enter to accept the default value (`https://circleci.com`).
- At the CircleCI organization name prompt, enter `actions-importer-labs`. This is the organization you'll be using throughout these labs.
```console
$ gh actions-importer configure
@@ -46,7 +46,7 @@ You will need to complete all of the setup instructions [here](./readme.md#confi
## Verify your environment
To verify our environment is configured correctly, we are going to run the `update` CLI command. The `update` CLI command will download the latest version of GitHub Actions Importer to your codespace.
To verify your environment is configured correctly, you are going to run the `update` CLI command. The `update` CLI command will download the latest version of GitHub Actions Importer to your codespace.
1. In the codespace terminal run the following command:
circle_ci/2-audit.md
+4 -4
View File
@@ -4,8 +4,8 @@ In this lab, you will use the `audit` command to get a high-level view of all pr
The `audit` command will perform the following steps:
1. Fetch all of the projects defined in an CircleCI organization.
2. Convert each pipeline to their equivalent GitHub Actions workflow.
1. Fetch all of the projects defined in a CircleCI organization.
2. Convert each pipeline to its equivalent GitHub Actions workflow.
3. Generate a report that summarizes how complete and complex of a migration is possible with GitHub Actions Importer.
## Prerequisites
@@ -17,7 +17,7 @@ The `audit` command will perform the following steps:
You will be performing an `audit` for the __actions-importer-labs__ CircleCI organization that was created for the purposes of these labs. Your environment was configured to use this organization during the [configure lab](./1-configure.md). The remaining information needed to perform an `audit` is:
1. Where do we want to store the result?
1. Where do you want to store the result?
- __tmp/audit__. This can be any path within the working directory that GitHub Actions Importer commands are executed from.
### Steps
@@ -194,7 +194,7 @@ Each pipeline will have a variety of files written that include:
- The converted workflow.
- Stack traces that can used to troubleshoot a failed pipeline conversion
## Inspect the workflow usage csv file
## Inspect the workflow usage .csv file
1. Open the `tmp/audit/workflow_usage.csv` file in the file explorer.
2. This file contains a comma-separated list of all actions, secrets, and runners that are used by each successfully converted pipeline:
circle_ci/4-dry-run.md
+1 -1
View File
@@ -13,7 +13,7 @@ In this lab you will use the `dry-run` command to convert a CircleCI pipeline to
You will be performing a dry run migration against a CircleCI project. Answer the following questions before running this command:
1. What project do you want to convert?
- __circleci-demo-ruby-rails__. This is one of the sample projects avaiable in the CircleCI actions-importer-labs organization.
- __circleci-demo-ruby-rails__. This is one of the sample projects available in the CircleCI actions-importer-labs organization.
2. Where do you want to store the result?
- __tmp/dry-run__. This can be any path within the working directory that GitHub Actions Importer commands are executed from.
circle_ci/5-custom-transformers.md
+5 -5
View File
@@ -1,6 +1,6 @@
# Using custom transformers to customize GitHub Actions Importer's behavior
# Use custom transformers to customize GitHub Actions Importer's behavior
In this lab you will build upon the `dry-run` command to override GitHub Actions Importer's default behavior and customize the converted workflow using "custom transformers". Custom transformers can be used to:
In this lab, you will build upon the `dry-run` command to override GitHub Actions Importer's default behavior and customize the converted workflow using "custom transformers." Custom transformers can be used to:
1. Convert items that are not automatically converted.
2. Convert items that were automatically converted using different actions.
@@ -13,7 +13,7 @@ In this lab you will build upon the `dry-run` command to override GitHub Actions
2. Completed the [configure lab](./1-configure.md#configuring-credentials).
3. Completed the [dry-run lab](./4-dry-run.md).
## Perform a dry-run
## Perform a dry run
You will be performing a `dry-run` command to inspect the workflow that is converted by default. Run the following command within the codespace terminal:
@@ -98,7 +98,7 @@ transform "codecov_codecov_upload" do |_item|
end
```
This method can use any valid ruby syntax and should return a `Hash` that represents the YAML that should be generated for a given step. GitHub Actions Importer will use this method to convert a step with the provided identifier and will use the `item` parameter for the original values configured in CircleCI.
This method can use any valid Ruby syntax and should return a `Hash` that represents the YAML that should be generated for a given step. GitHub Actions Importer will use this method to convert a step with the provided identifier and will use the `item` parameter for the original values configured in CircleCI.
Now you can perform another `dry-run` command and use the `--custom-transformers` CLI option to provide this custom transformer. Run the following command within your codespace terminal:
@@ -187,7 +187,7 @@ end
</details>
That's it! Congratulations, you have overridden GitHub Actions Importer's default behavior by customizing the conversion of:
That's it. Congratulations, you have overridden GitHub Actions Importer's default behavior by customizing the conversion of:
- Unknown steps
- Environment variables
circle_ci/6-migrate.md
+5 -5
View File
@@ -27,7 +27,7 @@ Answer the following questions before running a `migrate` command:
gh actions-importer migrate circle-ci --target-url https://github.com/:owner/:repo --output-dir tmp/migrate --circle-ci-project circleci-hello-world
```
2. The command will write the URL to the pull request that was created when the command succeeds.
2. The command will write the URL to the pull request that is created when the command succeeds.
```console
$ gh actions-importer migrate circle-ci --target-url https://github.com/:owner/:repo --output-dir tmp/migrate --circle-ci-project circleci-hello-world
@@ -45,10 +45,10 @@ Next, you can inspect the "Files changed" in this pull request and see the conve
![action-run](https://user-images.githubusercontent.com/18723510/189924238-9f6799c7-e029-4695-a1de-a23666171992.png)
Finally, you can merge the pull request once your review has completed. You can then view the workflow running by selecting the "Actions" menu in the top navigation bar in GitHub.
Finally, you can merge the pull request once your review has completed. You can then view the workflow running by selecting the **Actions** menu in the top navigation bar in GitHub.
At this point, the migration has completed and you have successfully migrated a CircleCI pipeline to Actions!
At this point, the migration has completed and you have successfully migrated a CircleCI pipeline to Actions.
### Next Lab
### Next lab
This concludes all labs for migrating CircleCI pipelines to Actions with GitHub Actions Importer!
This concludes all labs for migrating CircleCI pipelines to Actions with GitHub Actions Importer.
circle_ci/readme.md
+5 -8
View File
@@ -1,6 +1,6 @@
# CircleCI to Actions migrations powered by GitHub Actions Importer
# CircleCI migrations powered by GitHub Actions Importer
The instructions below will guide you through configuring a GitHub Codespace environment that will be used in subsequent labs that demonstrate how to use GitHub Actions Importer to migrate CircleCI pipelines to GitHub Actions.
The instructions below will guide you through configuring a GitHub Codespace environment that you will use in subsequent labs to learn how to use GitHub Actions Importer to migrate CircleCI pipelines to GitHub Actions.
These steps **must** be completed prior to starting other labs.
@@ -12,8 +12,8 @@ These steps **must** be completed prior to starting other labs.
1. Start a new Codespace.
- Click the `Code` with button down arrow above repository on the repository's landing page.
- Click the `Codespaces` tab
- Click the `Code` button on your repository's landing page.
- Click the `Codespaces` tab.
- Click `Create codespaces on main` to create the codespace.
- After the Codespace has initialized there will be a terminal present.
@@ -34,7 +34,7 @@ These steps **must** be completed prior to starting other labs.
actions-importer/cli unknown
```
- If `gh actions-importer version` did not produce similar output, refer to the troubleshooting [guide](#troubleshoot-the-actions-importer/cli).
- If `gh actions-importer version` did not produce similar output, refer to the [troubleshooting section](#troubleshoot-the-github-actions-importer-cli).
## Labs for CircleCI
@@ -65,9 +65,6 @@ The CLI extension for GitHub Actions Importer can be manually installed by follo
✓ Installed extension github/gh-actions-importer
```
- If you get an error similar to the image below, then click the link in the terminal output to authorize the token.
- Restart the codespace after clicking the link.
![img](https://user-images.githubusercontent.com/26442605/169588015-9414404f-82b6-4d0f-89d4-5f0e6941b029.png)
- Verify GitHub Actions Importer CLI extension is installed and working by running the following command from the codespace's terminal:
```bash
readme.md
+8 -7
View File
@@ -1,16 +1,17 @@
# GitHub Actions Importer learning labs
# GitHub Actions Importer labs
[GitHub Actions Importer](https://docs.github.com/en/actions/migrating-to-github-actions/automating-migration-with-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.
> **Note**: GitHub Actions Importer is currently available as a public preview. Visit the [sign up page](https://github.com/features/actions-importer/signup) to request access to the preview.
## Choose your learning path
To get started:
1. Use the `actions/importer-labs` repository as a template to [generate](https://github.com/actions/importer-labs/generate) a new GitHub repository.
2. Select which learning path to begin with. There are currently learning paths for:
- [Migrations from Azure DevOps to GitHub Actions](/azure_devops/readme.md)
- [Migrations from CircleCI to GitHub Actions](/circle_ci/readme.md)
- [Migrations from GitLab to GitHub Actions](/gitlab/readme.md)
- [Migrations from Jenkins to GitHub Actions](/jenkins/readme.md)
- [Migrations from Travis CI to GitHub Actions](/travis/readme.md)
2. Choose where to start. There are currently learning paths for:
- [Migrating from Azure DevOps to GitHub Actions](/azure_devops/readme.md)
- [Migrating from CircleCI to GitHub Actions](/circle_ci/readme.md)
- [Migrating from GitLab to GitHub Actions](/gitlab/readme.md)
- [Migrating from Jenkins to GitHub Actions](/jenkins/readme.md)
- [Migrating from Travis CI to GitHub Actions](/travis/readme.md)
3. Each learning path describes how to configure your codespace, bootstrap a CI/CD environment, and troubleshoot GitHub Actions Importer.