Skip to content
This repository was archived by the owner on Nov 30, 2023. It is now read-only.

Commit 1faa2cd

Browse files
arilivigniarilivigni
committed
Setup template for importer-labs
0 parents  commit 1faa2cd

File tree

720 files changed

+26051
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

720 files changed

+26051
-0
lines changed

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2023 GitHub
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎azure_devops/1-configure.md

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Configure credentials for GitHub Actions Importer
2+
3+
In this lab, you will use the `configure` CLI command to set the required credentials and information for GitHub Actions Importer to use when working with Azure DevOps and GitHub.
4+
5+
You will need to complete all of the setup instructions [here](./readme.md#configure-your-codespace) prior to performing this lab.
6+
7+
## Configuring credentials
8+
9+
1. Create an Azure DevOps personal access token (PAT).
10+
__Note__: you can skip this step if you still have the PAT created during the setup steps [here](./readme.md#bootstrap-your-azure-devops-organization).
11+
- Navigate to your existing organization (<https://dev.azure.com/:organization>) in your browser.
12+
- In the top right corner of your screen, click `User settings`.
13+
- Click `Personal access tokens`.
14+
- Select `+ New Token`
15+
- 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.
16+
- Select the following scopes (you may need to `Show all scopes` to reveal all scopes):
17+
- Agents Pool: `Read`
18+
- Build: `Read & execute`
19+
- Code: `Read & write`
20+
- Project and Team: `Read, write, & manage`
21+
- Release: `Read`
22+
- Service Connections: `Read`
23+
- Task Groups: `Read`
24+
- Variable Groups: `Read`
25+
- Click `Create`.
26+
- Copy the generated API token and save it in a safe location.
27+
28+
2. Create a GitHub personal access token (PAT):
29+
- Open github.com in a new browser tab.
30+
- In the top right corner of the UI, click your profile photo and then click `Settings`.
31+
- In the left panel, click `Developer Settings`.
32+
- Click `Personal access tokens` and then `Tokens (classic)` (if present).
33+
- Click `Generate new token` and then `Generate new token (classic)`. You may be required to authenticate with GitHub during this step.
34+
- Name your token in the `Note` field.
35+
- Select the following scope: `workflow`.
36+
- Click `Generate token`.
37+
- Copy the generated PAT and save it in a safe location.
38+
39+
3. Run the `configure` CLI command:
40+
- Select the `TERMINAL` tab from within the codespace terminal.
41+
- Run the following command: `gh actions-importer configure`.
42+
- Use the down arrow key to highlight `Azure DevOps`, press the spacebar to select, and then press enter to continue.
43+
- At the GitHub PAT prompt, enter the GitHub PAT generated in step 2 and press enter.
44+
- At the GitHub URL prompt, enter the GitHub instance URL or press enter to accept the default value (`https://github.com`).
45+
- At the Azure DevOps token prompt, enter the access token from step 1 and press enter.
46+
- At the Azure DevOps URL prompt, enter your Azure DevOps URL or press enter to accept the default value (`https://dev.azure.com`).
47+
- At the prompt, enter your Azure DevOps organization name. This should be the same organization used in the setup steps [here](./readme.md#bootstrap-your-azure-devops-organization).
48+
- At the prompt, enter your Azure DevOps project name. This should be the same project name used in the setup steps [here](./readme.md#bootstrap-your-azure-devops-organization).
49+
50+
```console
51+
$ gh actions-importer configure
52+
✔ Which CI providers are you configuring?: Azure DevOps
53+
Enter the following values (leave empty to omit):
54+
✔ Personal access token for GitHub: ***************
55+
✔ Base url of the GitHub instance: https://github.com
56+
✔ Personal access token for Azure DevOps: ***************
57+
✔ Base url of the Azure DevOps instance: https://dev.azure.com
58+
✔ Azure DevOps organization name: :organization
59+
✔ Azure DevOps project name: :project
60+
Environment variables successfully updated.
61+
```
62+
63+
## Verify your environment
64+
65+
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.
66+
67+
1. In the codespace terminal, run the following command:
68+
69+
```bash
70+
gh actions-importer update
71+
```
72+
73+
2. You should see a confirmation that you were logged into the GitHub Container Registry and the image was updated to the latest version.
74+
75+
```console
76+
$ gh actions-importer update
77+
Login Succeeded
78+
latest: Pulling from actions-importer/cli
79+
Digest: sha256:a7d00dee8a37e25da59daeed44b1543f476b00fa2c41c47f48deeaf34a215bbb
80+
Status: Image is up to date for ghcr.io/actions-importer/cli:latest
81+
ghcr.io/actions-importer/cli:latest
82+
```
83+
84+
### Next lab
85+
86+
[Perform an audit of an Azure DevOps project](2-audit.md)

‎azure_devops/2-audit.md

+208
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Perform an audit of an Azure DevOps project
2+
3+
In this lab, you will use the `audit` command to get a high-level view of all pipelines in an Azure DevOps organization or project.
4+
5+
The `audit` command will perform the following steps:
6+
7+
1. Fetch all of the projects defined in an Azure DevOps organization.
8+
2. Convert each pipeline to their equivalent GitHub Actions workflow.
9+
3. Generate a report that summarizes how complete and complex of a migration is possible with GitHub Actions Importer.
10+
11+
## Prerequisites
12+
13+
1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment and bootstrap an Azure DevOps project.
14+
2. Completed the [configure lab](./1-configure.md#configuring-credentials).
15+
16+
## Perform an audit
17+
18+
You will now perform an audit against the bootstrapped Azure DevOps project. Answer the following questions before running this command:
19+
20+
1. What is the Azure DevOps organization name that you want to audit?
21+
- __:organization__. This should be the same organization used in the setup steps [here](./readme.md#bootstrap-your-azure-devops-organization)
22+
23+
2. What is the Azure DevOps project name that you want to audit?
24+
- __:project__. This should be the same project name used in the setup steps [here](./readme.md#bootstrap-your-azure-devops-organization)
25+
26+
3. Where do you want to store the result?
27+
- __tmp/audit__. This can be any path within the working directory from which GitHub Actions Importer commands are executed.
28+
29+
### Steps
30+
31+
1. Navigate to the codespace terminal.
32+
2. Run the following command from the root directory:
33+
34+
```bash
35+
gh actions-importer audit azure-devops --output-dir tmp/audit
36+
```
37+
38+
__Note__: The Azure DevOps organization and project name can be omitted from the `audit` command because they were persisted in the `.env.local` file in the [configure lab](./1-configure.md). You can optionally provide these arguments on the command line with the `--azure-devops-organization` and `--azure-devops-project` CLI options.
39+
40+
3. The command will list all the files written to disk in green when the command succeeds.
41+
42+
## Inspect the output files
43+
44+
1. Find the `audit_summary.md` file in the file explorer.
45+
2. Right-click the `audit_summary.md` file and select `Open Preview`.
46+
3. This file contains details that summarize what percentage of your pipelines were converted automatically.
47+
48+
### Review audit summary
49+
50+
#### Pipelines
51+
52+
The pipeline summary section contains high level statistics regarding the conversion rate done by GitHub Actions Importer:
53+
54+
```md
55+
## Pipelines
56+
57+
Total: **5**
58+
59+
- Successful: **5 (100%)**
60+
- Partially successful: **0 (0%)**
61+
- Unsupported: **0 (0%)**
62+
- Failed: **0 (0%)**
63+
64+
### Job types
65+
66+
Supported: **5 (100%)**
67+
68+
- designer: **2**
69+
- YAML: **3**
70+
```
71+
72+
Here are some key terms in the "Pipelines" section:
73+
74+
- __Successful__ pipelines had 100% of the pipeline constructs and individual items converted automatically to their GitHub Actions equivalent.
75+
- __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.
76+
- __Unsupported__ pipelines are definition types that are not supported by GitHub Actions Importer. The following Azure DevOps pipeline types are supported:
77+
- Classic (designer)
78+
- YAML
79+
- Release
80+
- __Failed__ pipelines encountered a fatal error when being converted. This can occur for one of three reasons:
81+
- The pipeline was misconfigured and not valid in Azure DevOps.
82+
- GitHub Actions Importer encountered an internal error when converting it.
83+
- There was an unsuccessful network response, often due to invalid credentials, that caused the pipeline to be inaccessible.
84+
85+
The "Job types" section will summarize which types of pipelines are being used and which are supported or unsupported by GitHub Actions Importer.
86+
87+
#### Build steps
88+
89+
The build steps summary section presents an overview of the individual build steps that are used across all pipelines and how many were automatically converted by GitHub Actions Importer.
90+
91+
```md
92+
### Build steps
93+
94+
Total: **14**
95+
96+
Known: **14 (100%)**
97+
98+
- script: **4**
99+
- DotNetCoreCLI@2: **2**
100+
- 2c65196a-54fd-4a02-9be8-d9d1837b7c5d@0: **2**
101+
- 333b11bd-d341-40d9-afcf-b32d5ce6f23b@2: **2**
102+
- e213ff0f-5d5c-4791-802d-52ea3e7be1f1@2: **2**
103+
- NodeTool@0: **1**
104+
- checkout: **1**
105+
106+
Actions: **19**
107+
108+
- run: **10**
109+
- actions/checkout@v2: **6**
110+
- nuget/setup-nuget@v1: **2**
111+
- actions/setup-node@v2: **1**
112+
```
113+
114+
Here are some key terms in the "Build steps" section:
115+
116+
- A __known__ build step is a step that was automatically converted to an equivalent action.
117+
- An __unknown__ build step is a step that was not automatically converted to an equivalent action.
118+
- An __unsupported__ build step is a step that is either:
119+
- A step that is fundamentally not supported by GitHub Actions.
120+
- A step that is configured in a way that is incompatible with GitHub Actions.
121+
- An __action__ is a list of the actions that were used in the converted workflows. This is important for the following scenarios:
122+
- Gathering the list of actions to sync to your appliance if you use GitHub Enterprise Server.
123+
- Defining an organization-level allowlist of actions that can be used. This list of actions is a comprehensive list of which actions their security and/or compliance teams will need to review.
124+
125+
There is an equivalent breakdown of build triggers, environment variables, and other uncategorized items displayed in the audit summary file.
126+
127+
#### Manual Tasks
128+
129+
The manual tasks summary section presents an overview of the manual tasks that you will need to perform that GitHub Actions Importer is not able to complete automatically.
130+
131+
```md
132+
### Manual tasks
133+
134+
Total: **1**
135+
136+
Self hosted runners: **1**
137+
138+
- `mechamachine`: **1**
139+
```
140+
141+
Here are some key terms in the "Manual tasks" section:
142+
143+
- 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.
144+
- 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.
145+
146+
#### Files
147+
148+
The final section of the audit report provides a manifest of all of the files that are written to disk during the audit. These files include:
149+
150+
```md
151+
### Successful
152+
153+
#### actions-importer-bootstrap/pipelines/pipeline2
154+
155+
- [pipelines/actions-importer-bootstrap/pipelines/pipeline2/.github/workflows/pipeline2.yml](pipelines/actions-importer-bootstrap/pipelines/pipeline2/.github/workflows/pipeline2.yml)
156+
- [pipelines/actions-importer-bootstrap/pipelines/pipeline2/config.json](pipelines/actions-importer-bootstrap/pipelines/pipeline2/config.json)
157+
- [pipelines/actions-importer-bootstrap/pipelines/pipeline2/source.yml](pipelines/actions-importer-bootstrap/pipelines/pipeline2/source.yml)
158+
159+
#### actions-importer-bootstrap/pipelines/pipeline1
160+
161+
- [pipelines/actions-importer-bootstrap/pipelines/pipeline1/.github/workflows/pipeline1.yml](pipelines/actions-importer-bootstrap/pipelines/pipeline1/.github/workflows/pipeline1.yml)
162+
- [pipelines/actions-importer-bootstrap/pipelines/pipeline1/config.json](pipelines/actions-importer-bootstrap/pipelines/pipeline1/config.json)
163+
- [pipelines/actions-importer-bootstrap/pipelines/pipeline1/source.yml](pipelines/actions-importer-bootstrap/pipelines/pipeline1/source.yml)
164+
165+
#### actions-importer-bootstrap/pipelines/custom-transformer-example
166+
167+
- [pipelines/actions-importer-bootstrap/pipelines/custom-transformer-example/.github/workflows/custom-transformer-example.yml](pipelines/actions-importer-bootstrap/pipelines/custom-transformer-example/.github/workflows/custom-transformer-example.yml)
168+
- [pipelines/actions-importer-bootstrap/pipelines/custom-transformer-example/config.json](pipelines/actions-importer-bootstrap/pipelines/custom-transformer-example/config.json)
169+
- [pipelines/actions-importer-bootstrap/pipelines/custom-transformer-example/source.yml](pipelines/actions-importer-bootstrap/pipelines/custom-transformer-example/source.yml)
170+
```
171+
172+
Each pipeline will have a variety of files written that include:
173+
174+
- The original pipeline as it was defined in Azure DevOps.
175+
- Any network responses used to convert a pipeline.
176+
- The converted workflow.
177+
- Stack traces that can used to troubleshoot a failed pipeline conversion
178+
179+
## Inspect the workflow usage .csv file
180+
181+
1. Open the `tmp/audit/workflow_usage.csv` file in the file explorer.
182+
2. This file contains a comma-separated list of all actions, secrets, and runners that are used by each successfully converted pipeline:
183+
184+
```csv
185+
Pipeline,Action,File path
186+
actions-importer-bootstrap/pipelines/pipeline2,actions/checkout@v2,tmp/audit/pipelines/actions-importer-bootstrap/pipelines/pipeline2/.github/workflows/pipeline2.yml
187+
actions-importer-bootstrap/pipelines/pipeline1,actions/checkout@v2,tmp/audit/pipelines/actions-importer-bootstrap/pipelines/pipeline1/.github/workflows/pipeline1.yml
188+
actions-importer-bootstrap/pipelines/custom-transformer-example,actions/checkout@v2,tmp/audit/pipelines/actions-importer-bootstrap/pipelines/custom-transformer-example/.github/workflows/custom-transformer-example.yml
189+
actions-importer-bootstrap/pipelines/custom-transformer-example,actions/setup-node@v2,tmp/audit/pipelines/actions-importer-bootstrap/pipelines/custom-transformer-example/.github/workflows/custom-transformer-example.yml
190+
191+
Pipeline,Secret,File path
192+
193+
194+
Pipeline,Runner,File path
195+
actions-importer-bootstrap/pipelines/pipeline2,mechamachine,tmp/audit/pipelines/actions-importer-bootstrap/pipelines/pipeline2/.github/workflows/pipeline2.yml
196+
actions-importer-bootstrap/pipelines/custom-transformer-example,mechamachine,tmp/audit/pipelines/actions-importer-bootstrap/pipelines/custom-transformer-example/.github/workflows/custom-transformer-example.yml
197+
```
198+
199+
The contents of this file can be useful in answering questions similar to the following:
200+
201+
- What workflows will depend on which actions?
202+
- What workflows use an action that must go through a security review?
203+
- What workflows use specific secrets?
204+
- What workflows use specific runners?
205+
206+
### Next lab
207+
208+
[Forecast potential build runner usage](3-forecast.md)

0 commit comments

Comments
 (0)