From 5e4fef4f59925019a6f50b69411c8bb2f6dccf52 Mon Sep 17 00:00:00 2001 From: Begona Guereca Date: Thu, 15 Sep 2022 13:40:40 -0700 Subject: [PATCH 1/7] Added travis migrate lab --- travis/5-migrate.md | 51 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 travis/5-migrate.md diff --git a/travis/5-migrate.md b/travis/5-migrate.md new file mode 100644 index 0000000..0efd2e9 --- /dev/null +++ b/travis/5-migrate.md @@ -0,0 +1,51 @@ +# Perform a production migration of a Travis CI pipeline + +In this lab, you will use the `migrate` command to convert a Travis CI pipeline and open a pull request with the equivalent Actions workflow. + +## Prerequisites + +1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment. +2. Completed the [configure lab](./1-configure.md#configuring-credentials). +3. Completed the [dry-run lab](./3-dry-run.md). +4. Completed the [custom transformers lab](./4-custom-transformers.md). + +## Performing a migration + +Answer the following questions before running a `migrate` command: + +1. What project do you want to migrate? + - __circleci-hello-world__ +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? + - __this repository__. The URL should follow the pattern with `:owner` and `:repo` replaced with your values. + +### Steps + +1. Run the following `migrate` command in the codespace terminal. Ensure the values in `--target-url` for `:owner` and `:repo` are replaced with your values: + + ```bash + gh valet migrate travis-ci --target-url https://github.com/:owner/:repo --output-dir ./tmp/migrate --travis-ci-repository "deploy-example" + ``` + +2. The command will write the URL to the pull request that was created when the command succeeds. + + ![pr](https://user-images.githubusercontent.com/19557880/190496147-2f8af72d-51d9-426b-94cf-5d0d7fe02eb3.png) + +3. Open the generated pull request in a new browser tab. + +### Inspect the pull request + +The first thing to notice about the pull request is that there is a list of manual steps to complete. + +Next, you can inspect the "Files changed" in this pull request and see the converted workflow that is being added. Any additional changes or code reviews that were needed should be done in this pull request. + +![action-run](https://user-images.githubusercontent.com/19557880/190496147-2f8af72d-51d9-426b-94cf-5d0d7fe02eb3.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. + +At this point, the migration has completed and you have successfully migrated a Travis CI pipeline to Actions! + +### Next Lab + +[Forecast potential build runner usage](6-forecast.md) From 314f8acbd5246a44552fe5bbf22e51ad02f9aec1 Mon Sep 17 00:00:00 2001 From: Begona Guereca Date: Thu, 15 Sep 2022 14:32:59 -0700 Subject: [PATCH 2/7] Travis CI forecast lab --- travis/6-forecast.md | 100 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 travis/6-forecast.md diff --git a/travis/6-forecast.md b/travis/6-forecast.md new file mode 100644 index 0000000..66bcd30 --- /dev/null +++ b/travis/6-forecast.md @@ -0,0 +1,100 @@ +# Forecast potential build runner usage + +In this lab you will use the `forecast` command to forecast potential GitHub Actions usage by computing metrics from completed pipeline runs in Travis CI. + +## Prerequisites + +1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment. +2. Completed the [configure lab](./1-configure.md#configuring-credentials). + +## Perform a forecast + +Answer the following questions before running the `forecast` command: + +1. What is the date you want to start forecasting from? + - **2022-09-02**. This date is needed as it is prior to when the bulk of builds were trigger in the demo Travis CI organization for these labs. This value defaults to the date one week ago, however, you should use a start date that will show a representative view of typical usage. +2. Where do you want to store the results? + - **./tmp/forecast_reports** + +### Steps + +1. Navigate to your codespace terminal +2. Run the following command from the root directory: + + ```bash + gh valet forecast travis-ci --output-dir ./tmp/forecast_reports --start-date 2022-09-02 + ``` + +3. The command will list all the files written to disk when the command succeeds. + + ![command-output](https://user-images.githubusercontent.com/19557880/190510549-e2d4eacd-2d3f-4778-8cf5-f5187f78350a.png) + +## Review the forecast report + +The forecast report, logs, and completed job data will be located within the `tmp/forecast_reports` folder. + +1. Find the `forecast_report.md` file in the file explorer. +2. Right-click the `forecast_report.md` file and select `Open Preview`. +3. This file contains metrics used to forecast potential GitHub Actions usage. + +### Total + +The "Total" section of the forecast report contains high level statistics related to all the jobs completed after the `--start-date` CLI option: + +```md +- Job count: **18** +- Pipeline count: **13** + +- Execution time + + - Total: **46 minutes** + - Median: **1 minutes** + - P90: **6 minutes** + - Min: **0 minutes** + - Max: **10 minutes** + +- Queue time + + - Median: **0 minutes** + - P90: **0 minutes** + - Min: **0 minutes** + - Max: **0 minutes** + +- Concurrent jobs + + - Median: **0** + - P90: **0** + - Min: **0** + - Max: **4** +``` + +Here are some key terms of items defined in the forecast report: + +- The `job count` is the total number of completed jobs. +- The `pipeline count` is the number of unique pipelines used. +- `Execution time` describes the amount of time a runner spent on a job. This metric can be used to help plan for the cost of GitHub-hosted runners. + - This metric is correlated to how much you should expect to spend in GitHub Actions. This will vary depending on the hardware used for these minutes. You can use the [Actions pricing calculator](https://github.com/pricing/calculator) to estimate a dollar amount. +- `Queue time` metrics describe the amount of time a job spent waiting for a runner to be available to execute it. +- `Concurrent jobs` metrics describe the amount of jobs running at any given time. This metric can be used to define the number of runners a customer should configure. + +Additionally, these metrics are defined for each queue of runners defined in Travis CI. This is especially useful if there are a mix of hosted/self-hosted runners or high/low spec machines to see metrics specific to different types of runners. + +## Forecasting multiple providers + +You can examine the available options for the `forecast` command by running `gh valet forecast --help`. When you do this you will see the `--source-file-path` option: + +![img](https://user-images.githubusercontent.com/19557880/190511652-081ae8c3-c37e-4c5f-9e7f-8fcd9fe63b3a.png) + +You can use the `--source-file-path` CLI option to combine data from multiple reports into a single report. This becomes useful if you use multiple CI/CD providers and want to get a holistic view of the runner usage. This works by using the `.json` files generated by `forecast` commands as space-delimited values for the `--source-file-path` CLI option. Optionally, this value could be a glob pattern to dynamically specify the list of files (e.g. `**/*.json`). + +Run the following command from within the codespace terminal: + +```bash +gh valet forecast --source-file-path tmp/**/jobs/*.json -o tmp/combined-forecast +``` + +You can now inspect the output of the command to see a forecast report using all of the files matching the `tmp/**/jobs/*.json` pattern. + +## Next steps + +This concludes all labs for migrating Travis CI pipelines to Actions with Valet! From 4f34acd39ecf064741501f52215135921a564daf Mon Sep 17 00:00:00 2001 From: Begona Guereca Date: Thu, 15 Sep 2022 15:36:02 -0700 Subject: [PATCH 3/7] Travis CI Audit lab --- travis/2-audit.md | 338 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 338 insertions(+) create mode 100644 travis/2-audit.md diff --git a/travis/2-audit.md b/travis/2-audit.md new file mode 100644 index 0000000..7c10b3b --- /dev/null +++ b/travis/2-audit.md @@ -0,0 +1,338 @@ +# Perform an audit of CircleCI + +In this lab, you will use the `audit` command to get a high-level view of all projects in a Travis CI organization. + +The `audit` command operates by fetching all of the projects defined in a Travis CI organization, converting each to their equivalent GitHub Actions workflow, and writing a report that summarizes how complete and complex of a migration is possible with Valet. + +## Prerequisites + +1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your Codespace environment. +2. Completed the [configure lab](./1-configure.md#configure-credentials-for-valet). + +## Perform an audit + +We will be performing an audit against the **labs-data** organization in Travis CI, which was created for the purposes of this lab. Valet was already been set to use this organization during the configure lab. The only remaining information needed for the `audit` command is: + +1. Where do we want to store the result? + - **./tmp/audit**. This can be any path within the working directory that Valet commands are executed from. + +### Steps + +1. Navigate to the codespace terminal. +2. Run the following command from the root directory: + + ```bash + gh valet audit travis-ci --output-dir tmp/audit + ``` + +3. The command will list all the files written to disk in green when the command succeeds. + +## Inspect the output files + +1. Find the `audit_summary.md` file in the file explorer. +2. Right-click the `audit_summary.md` file and select `Open Preview`. +3. This file contains details that summarizes what percentage of your pipelines were converted automatically. + +### Review audit summary + +#### Pipelines + +The pipeline summary section contains high level statistics regarding the conversion rate done by Valet: + +```md +# Audit summary + +Summary for [Travis CI instance](https://travis-ci.com/valet-travis-labs) + +- Valet version: **0.1.0.13539 (5bb6c723d6db3688ea0653e14bbf3c63df445bfc)** +- Performed at: **9/15/22 at 22:24** + +## Pipelines + +Total: **6** + +- Successful: **0 (0%)** +- Partially successful: **6 (100%)** +- Unsupported: **0 (0%)** +- Failed: **0 (0%)** + +### Job types + +Supported: **6 (100%)** + +- ruby: **2** +- c: **1** +- nodejs: **1** +- php: **1** +- python: **1** + +### Build steps + +Total: **29** + +Known: **26 (89%)** + +- script: **7** +- install: **6** +- before_script: **3** +- rvm: **2** +- after_deploy: **2** +- ccache: **1** +- pushover: **1** +- dependencies: **1** +- before_deploy: **1** +- php: **1** +- irc: **1** + +Unknown: **1 (3%)** + +- codedeploy: **1** + +Unsupported: **2 (6%)** + +- sudo: **2** + +Actions: **32** + +- run: **19** +- actions/checkout@v2: **7** +- ruby/setup-ruby@v1: **2** +- actions/cache@v2: **1** +- desiderati/github-action-pushover@v1: **1** +- shivammathur/setup-php@v2: **1** +- rectalogic/notify-irc@v1: **1** + +### Triggers + +Total: **36** + +Known: **36 (100%)** + +- crons: **6** +- branches: **6** +- config_validation: **6** +- build_pull_requests: **6** +- build_pushes: **6** +- builds_only_with_travis_yml: **6** + +Actions: **12** + +- pull_request: **6** +- push: **6** + +### Environment + +Total: **1** + +Known: **1 (100%)** + +- DB: **1** + +Actions: **1** + +- DB: **1** + +### Other + +Total: **18** + +Known: **12 (66%)** + +- auto_cancel_pull_requests: **6** +- auto_cancel_pushes: **6** + +Unknown: **6 (33%)** + +- maximum_number_of_builds: **6** + +Actions: **3** + +- matrix: **2** +- DB: **1** + +### Manual tasks + +Total: **1** + +Secrets: **1** + +- `${{ secrets.PUSHOVER_USER_KEY }}`: **1** + +### Partially successful + +#### valet-travis-labs/deploy-example + +- [valet-travis-labs/deploy-example.yml](valet-travis-labs/deploy-example.yml) +- [valet-travis-labs/deploy-example.config.json](valet-travis-labs/deploy-example.config.json) +- [valet-travis-labs/deploy-example.source.yml](valet-travis-labs/deploy-example.source.yml) + +#### valet-travis-labs/c-sharp-example + +- [valet-travis-labs/c-sharp-example.yml](valet-travis-labs/c-sharp-example.yml) +- [valet-travis-labs/c-sharp-example.config.json](valet-travis-labs/c-sharp-example.config.json) +- [valet-travis-labs/c-sharp-example.source.yml](valet-travis-labs/c-sharp-example.source.yml) + +#### valet-travis-labs/ruby-example + +- [valet-travis-labs/ruby-example.yml](valet-travis-labs/ruby-example.yml) +- [valet-travis-labs/ruby-example.config.json](valet-travis-labs/ruby-example.config.json) +- [valet-travis-labs/ruby-example.source.yml](valet-travis-labs/ruby-example.source.yml) + +#### valet-travis-labs/nodejs-example + +- [valet-travis-labs/nodejs-example.yml](valet-travis-labs/nodejs-example.yml) +- [valet-travis-labs/nodejs-example.config.json](valet-travis-labs/nodejs-example.config.json) +- [valet-travis-labs/nodejs-example.source.yml](valet-travis-labs/nodejs-example.source.yml) + +#### valet-travis-labs/php-example + +- [valet-travis-labs/php-example.yml](valet-travis-labs/php-example.yml) +- [valet-travis-labs/php-example.config.json](valet-travis-labs/php-example.config.json) +- [valet-travis-labs/php-example.source.yml](valet-travis-labs/php-example.source.yml) + +#### valet-travis-labs/python + +- [valet-travis-labs/python.yml](valet-travis-labs/python.yml) +- [valet-travis-labs/python.config.json](valet-travis-labs/python.config.json) +- [valet-travis-labs/python.source.yml](valet-travis-labs/python.source.yml) + +``` + +Here are some key terms that can appear in the “Pipelines” section: + +- **Successful** pipelines had 0% of the pipeline constructs and individual items converted automatically to their GitHub Actions equivalent. +- **Partially successful** pipelines had 100% of all of the pipeline constructs converted, however, there were some individual items that were not converted automatically to their GitHub Actions equivalent. +- **Failed pipelines** encountered a fatal error when being converted. This can occur for one of three reasons: + - The pipeline was misconfigured and not valid in Travis CI. + - Valet encountered an internal error when converting it. + - There was an unsuccessful network response, often due to invalid credentials, that caused the pipeline to be inaccessible. + +The "Job types" section will summarize which types of pipelines are being used and which are supported or unsupported by Valet. + +#### Build steps + +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 Valet. + +```md +Total: **29** + +Known: **26 (89%)** + +- script: **7** +- install: **6** +- before_script: **3** +- rvm: **2** +- after_deploy: **2** +- ccache: **1** +- pushover: **1** +- dependencies: **1** +- before_deploy: **1** +- php: **1** +- irc: **1** + +Unknown: **1 (3%)** + +- codedeploy: **1** + +Unsupported: **2 (6%)** + +- sudo: **2** + +Actions: **32** + +- run: **19** +- actions/checkout@v2: **7** +- ruby/setup-ruby@v1: **2** +- actions/cache@v2: **1** +- desiderati/github-action-pushover@v1: **1** +- shivammathur/setup-php@v2: **1** +- rectalogic/notify-irc@v1: **1** +``` + +Here are some key terms that can appear in "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. +- An **unsupported** build step is a step that is either: + - A step that is fundamentally not supported by GitHub Actions. + - A step that is configured in a way that is incompatible with GitHub Actions. +- An **action** is a list of the actions that were used in the converted workflows. This is important for the following scenarios: + - Gathering the list of actions to sync to your appliance if you use GitHub Enterprise Server. + - 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. + +There is an equivalent breakdown of build triggers, environment variables, and other uncategorized items displayed in the audit summary file. + +#### Manual Tasks + +The manual tasks summary section presents an overview of the manual tasks that you will need to perform that Valet is not able to complete automatically. + +```md +### Manual tasks + +Total: **1** + +Secrets: **1** + +- `${{ secrets.PUSHOVER_USER_KEY }}`: **1** +``` + +Here are some key terms that can appear in “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. + +#### Files + +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: + +```md +### Partially successful + +#### valet-travis-labs/deploy-example + +- [valet-travis-labs/deploy-example.yml](valet-travis-labs/deploy-example.yml) +- [valet-travis-labs/deploy-example.config.json](valet-travis-labs/deploy-example.config.json) +- [valet-travis-labs/deploy-example.source.yml](valet-travis-labs/deploy-example.source.yml) + +#### valet-travis-labs/c-sharp-example + +- [valet-travis-labs/c-sharp-example.yml](valet-travis-labs/c-sharp-example.yml) +- [valet-travis-labs/c-sharp-example.config.json](valet-travis-labs/c-sharp-example.config.json) +- [valet-travis-labs/c-sharp-example.source.yml](valet-travis-labs/c-sharp-example.source.yml) + +#### valet-travis-labs/ruby-example + +- [valet-travis-labs/ruby-example.yml](valet-travis-labs/ruby-example.yml) +- [valet-travis-labs/ruby-example.config.json](valet-travis-labs/ruby-example.config.json) +- [valet-travis-labs/ruby-example.source.yml](valet-travis-labs/ruby-example.source.yml) + +#### valet-travis-labs/nodejs-example + +- [valet-travis-labs/nodejs-example.yml](valet-travis-labs/nodejs-example.yml) +- [valet-travis-labs/nodejs-example.config.json](valet-travis-labs/nodejs-example.config.json) +- [valet-travis-labs/nodejs-example.source.yml](valet-travis-labs/nodejs-example.source.yml) + +#### valet-travis-labs/php-example + +- [valet-travis-labs/php-example.yml](valet-travis-labs/php-example.yml) +- [valet-travis-labs/php-example.config.json](valet-travis-labs/php-example.config.json) +- [valet-travis-labs/php-example.source.yml](valet-travis-labs/php-example.source.yml) + +#### valet-travis-labs/python + +- [valet-travis-labs/python.yml](valet-travis-labs/python.yml) +- [valet-travis-labs/python.config.json](valet-travis-labs/python.config.json) +- [valet-travis-labs/python.source.yml](valet-travis-labs/python.source.yml) + +``` + +Each pipeline will have a variety of files written that include: + +- The original pipeline as it was defined in GitHub. +- Any network responses used to convert a pipeline. +- The converted workflow. +- Stack traces that can used to troubleshoot a failed pipeline conversion + +### Next lab + +[Perform a dry-run of a Travis CI pipeline](3-dry-run.md) From 6f181fc899165e701d004f6e7c38e6cfb000871d Mon Sep 17 00:00:00 2001 From: Begona Guereca Date: Fri, 16 Sep 2022 09:39:22 -0700 Subject: [PATCH 4/7] Update travis/5-migrate.md --- travis/5-migrate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/travis/5-migrate.md b/travis/5-migrate.md index 0efd2e9..1986da2 100644 --- a/travis/5-migrate.md +++ b/travis/5-migrate.md @@ -14,7 +14,7 @@ In this lab, you will use the `migrate` command to convert a Travis CI pipeline Answer the following questions before running a `migrate` command: 1. What project do you want to migrate? - - __circleci-hello-world__ + - __deploy-example__ 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? From 9d911df691c84282643cf4cc58ec567e03b21c0e Mon Sep 17 00:00:00 2001 From: Begona Guereca Date: Fri, 16 Sep 2022 09:52:42 -0700 Subject: [PATCH 5/7] Update travis/5-migrate.md --- travis/5-migrate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/travis/5-migrate.md b/travis/5-migrate.md index 1986da2..8dcf3db 100644 --- a/travis/5-migrate.md +++ b/travis/5-migrate.md @@ -30,7 +30,7 @@ Answer the following questions before running a `migrate` command: 2. The command will write the URL to the pull request that was created when the command succeeds. - ![pr](https://user-images.githubusercontent.com/19557880/190496147-2f8af72d-51d9-426b-94cf-5d0d7fe02eb3.png) + ![pr](https://user-images.githubusercontent.com/19557880/190689859-d16a678b-f08f-44c1-a819-780ea967ecaf.png) 3. Open the generated pull request in a new browser tab. From 63b163ad5f55c74e1530f8aecfbe283824c8904c Mon Sep 17 00:00:00 2001 From: Begona Guereca Date: Fri, 16 Sep 2022 09:55:49 -0700 Subject: [PATCH 6/7] Update travis/2-audit.md Co-authored-by: Ethan Dennis --- travis/2-audit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/travis/2-audit.md b/travis/2-audit.md index 7c10b3b..57938e5 100644 --- a/travis/2-audit.md +++ b/travis/2-audit.md @@ -11,7 +11,7 @@ The `audit` command operates by fetching all of the projects defined in a Travis ## Perform an audit -We will be performing an audit against the **labs-data** organization in Travis CI, which was created for the purposes of this lab. Valet was already been set to use this organization during the configure lab. The only remaining information needed for the `audit` command is: +You will be performing an audit against the **labs-data** Travis CI organization that was created for the purposes of this lab. 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? - **./tmp/audit**. This can be any path within the working directory that Valet commands are executed from. From d8b35d040638d03c050caab681750d4571d992b2 Mon Sep 17 00:00:00 2001 From: Begona Guereca Date: Fri, 16 Sep 2022 12:31:27 -0700 Subject: [PATCH 7/7] Update travis/2-audit.md Co-authored-by: Luke Cheung Engle <99493186+luke-engle@users.noreply.github.com> --- travis/2-audit.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/travis/2-audit.md b/travis/2-audit.md index 57938e5..077dc5e 100644 --- a/travis/2-audit.md +++ b/travis/2-audit.md @@ -2,7 +2,10 @@ In this lab, you will use the `audit` command to get a high-level view of all projects in a Travis CI organization. -The `audit` command operates by fetching all of the projects defined in a Travis CI organization, converting each to their equivalent GitHub Actions workflow, and writing a report that summarizes how complete and complex of a migration is possible with Valet. +The `audit` command operates by performing the following: +- Fetching all of the projects defined in a Travis CI organization. +- Converting each to their equivalent GitHub Actions workflow. +- Generating a report that summarizes how complete and complex of a migration is possible with Valet. ## Prerequisites