From 2bead723663744991e2117bc08f6ed28855d5d66 Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Tue, 8 Aug 2023 15:05:07 -0600 Subject: [PATCH 01/18] Add in the basic bamboo.yml --- bamboo/bootstrap/config.yml | 3 ++ .../bootstrap/source_files/bamboo/bamboo.yml | 29 +++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 bamboo/bootstrap/config.yml create mode 100644 bamboo/bootstrap/source_files/bamboo/bamboo.yml diff --git a/bamboo/bootstrap/config.yml b/bamboo/bootstrap/config.yml new file mode 100644 index 0000000..16e98e2 --- /dev/null +++ b/bamboo/bootstrap/config.yml @@ -0,0 +1,3 @@ +source_files: + - repository_slug: NEW/ROCKET + path: bamboo/bootstrap/source_files/bamboo/bamboo.yml diff --git a/bamboo/bootstrap/source_files/bamboo/bamboo.yml b/bamboo/bootstrap/source_files/bamboo/bamboo.yml new file mode 100644 index 0000000..9d3e4ef --- /dev/null +++ b/bamboo/bootstrap/source_files/bamboo/bamboo.yml @@ -0,0 +1,29 @@ +--- +version: 2 + +variables: + global_variable: global_variable_value + plan_variable_override: plan_variable_overrid + +plan: + project-key: NEW + key: ROCKET + name: Build the rockets + +# List of plan's stages and jobs +stages: + - Build the rocket stage: + - Build + +#Job definition +Build: + tasks: + - script: + - mkdir -p falcon/red + - echo wings > falcon/red/wings + - sleep 1 + - echo 'Built it' + # Job's artifacts. Artifacts are shared by default. + artifacts: + - name: Red rocket built + pattern: falcon/red/wings From dd7f063fed3ff5e4ba87a8830ed3cab86b4ccb3a Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Fri, 15 Sep 2023 12:20:42 -0600 Subject: [PATCH 02/18] Add bamboo lab --- bamboo/1-configure.md | 49 ++++++ bamboo/2-audit.md | 160 ++++++++++++++++++ bamboo/3-dry-run.md | 58 +++++++ bamboo/4-migrate.md | 53 ++++++ bamboo/bootstrap/config.yml | 2 +- .../bootstrap/source_files/bamboo/bamboo.yml | 78 ++++++--- bamboo/readme.md | 69 ++++++++ readme.md | 1 + 8 files changed, 446 insertions(+), 24 deletions(-) create mode 100644 bamboo/1-configure.md create mode 100644 bamboo/2-audit.md create mode 100644 bamboo/3-dry-run.md create mode 100644 bamboo/4-migrate.md create mode 100644 bamboo/readme.md diff --git a/bamboo/1-configure.md b/bamboo/1-configure.md new file mode 100644 index 0000000..a389472 --- /dev/null +++ b/bamboo/1-configure.md @@ -0,0 +1,49 @@ +# Configure credentials for GitHub Actions Importer + +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 Bamboo and GitHub. + +You will need to complete all of the setup instructions [here](./readme.md#configure-your-codespace) prior to performing this lab. + +## Configuring credentials + +1. Create a GitHub personal access token (PAT): + - Open github.com in a new browser tab. + - In the top right corner 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. + - Name your token in the `Note` field. + - Select the following scope: `workflow`. + - Click `Generate token`. + - Copy the generated PAT and save it in a safe location. + +2. Run the `configure` CLI command: + - Select the `TERMINAL` tab from within the codespace terminal. + - Run the following command: `gh actions-importer configure`. + - Use the down arrow key to highlight `Bamboo`, press the spacebar to select, and then press enter to continue. + - At the GitHub PAT prompt, enter the GitHub PAT generated in step 2 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 Bamboo token prompt, enter the access token from step 1 and press enter. + - At the Bamboo URL prompt, enter your Bamboo URL. + +## Verify your environment + +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: + + ```bash + gh actions-importer update + ``` + +2. You should see a confirmation that you were logged into the GitHub Container Registry and the image was updated to the latest version. + + ```console + $ gh actions-importer update + Updating ghcr.io/actions-importer/cli:latest... + ghcr.io/actions-importer/cli:latest up-to-date + ``` + +### Next lab + +[Perform an audit of audit of a Bamboo project](2-audit.md) diff --git a/bamboo/2-audit.md b/bamboo/2-audit.md new file mode 100644 index 0000000..b4405f5 --- /dev/null +++ b/bamboo/2-audit.md @@ -0,0 +1,160 @@ +# Perform an audit of an Bamboo plan + +In this lab, you will use the `audit` command to get a high-level view of all pipelines in an Bamboo config file. This lab uses local config files to demonstrate the actions-importer functionality. + +The `audit` command will perform the following steps: + +1. Determine the build plans and deployment projects defined in a local config file. +2. Convert each pipeline to their equivalent GitHub Actions workflow. +3. Generate a report that summarizes how complete and complex of a migration is possible with GitHub Actions Importer. + +## Prerequisites + +1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment and bootstrap an Bamboo project. +2. Completed the [configure lab](./1-configure.md#configuring-credentials). + +## Perform an audit + +You will audit the configured Bamboo pipelines. Answer the following questions before running this command: + +1. Where is the local configuration file? + - __bamboo/bootstrap/config.yml__ + +2. Where do you want to store the result? + - __tmp/audit__. This can be any path within the working directory from which GitHub Actions Importer commands are executed. + +### Steps + +1. Navigate to the codespace terminal. +2. Run the following command from the root directory: + + ```bash + gh actions-importer audit bamboo -o tmp/audit --config-file-path bamboo/bootstrap/config.yml + ``` + +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 summarize 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 GitHub Actions Importer: + +```md +## Pipelines + +Total: **1** + +- Successful: **1 (100%)** +- Partially successful: **0 (0%)** +- Unsupported: **0 (0%)** +- Failed: **0 (0%)** +``` + +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. +- __Unsupported__ pipelines are definition types that are not supported by GitHub Actions Importer. +- __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 Bamboo. + - GitHub Actions Importer 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. + +#### Job Types +The "Job types" section will summarize which types of pipelines are being used and which are supported or unsupported by GitHub Actions Importer. + +``` +### Job types + +Supported: **1 (100%)** + +- build: **1** +``` + +#### 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 GitHub Actions Importer. + +```md +### Build steps + +Total: **2** + +Known: **2 (100%)** + +- script: **1** +- checkout: **1** + +Actions: **3** + +- actions/upload-artifact@v3.1.1: **1** +- run: **1** +- actions/checkout@v3.5.0: **1** +``` + +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. +- 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 GitHub Actions Importer is not able to complete automatically. + +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. + +#### Files + +The final section of the audit report provides a manifest of all of the files that are written to disk during the audit. + +Each pipeline will have a variety of files written that include: + +- The original pipeline as it was defined in Bamboo. +- Any network responses used to convert a pipeline. +- The converted workflow. +- Stack traces that can used to troubleshoot a failed pipeline conversion + +## 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: + + ```csv + Pipeline,Action,File path + mars/rocket,actions/checkout@v3.5.0,tmp/audit/build/mars/rocket/.github/workflows/rocket.yml + mars/rocket,actions/upload-artifact@v3.1.1,tmp/audit/build/mars/rocket/.github/workflows/rocket.yml + + Pipeline,Secret,File path + + + Pipeline,Runner,File path + ``` + +The contents of this file can be useful in answering questions similar to the following: + +- What workflows will depend on which actions? +- What workflows use an action that must go through a security review? +- What workflows use specific secrets? +- What workflows use specific runners? + +### Next lab + +[Perform a dry run of a individual pipeline](3-dry-run.md) diff --git a/bamboo/3-dry-run.md b/bamboo/3-dry-run.md new file mode 100644 index 0000000..d262203 --- /dev/null +++ b/bamboo/3-dry-run.md @@ -0,0 +1,58 @@ +# Perform a dry-run migration of a Bamboo build plan. + +In this lab you will use the `dry-run` command to convert a Bamboo build plan to its equivalent GitHub 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 [audit lab](./2-audit.md). + +## Perform a dry run + +You will be performing a dry run against a single Bamboo pipeline. Answer the following questions before running this command: + +1. What is the planslug of the pipeline you want to convert? + + ``` + export PLAN_SLUG=MARS-ROCKET + ``` + +2. Where do you want to store the result? + - __tmp/dry-run__. This can be any path within the working directory from which GitHub Actions Importer commands are executed. + +3. Which file would you like to conver? + + ``` + export SOURCE_FILE_PATH=bamboo/bootstrap/source_files/bamboo/bamboo.yml + ``` + +4. Are you converting a build or deployment plan? + - The supplied configuration is a build plan. + +### Steps + +1. Navigate to your codespace terminal. +2. Run the following command from the root directory: + + ```bash + gh actions-importer dry-run bamboo build --source-file-path $SOURCE_FILE_PATH -p $PLAN_SLUG--output-dir tmp/dry-run + ``` + +3. The command will list all the files written to disk when the command succeeds. + + ```console + $ gh actions-importer dry-run bamboo build + ``` + +4. View the converted workflow: + - Find `tmp/dry-run/test_pipeline/.github/workflows` in the file explorer pane in your codespace. + - Click `test_pipeline.yml` to open. + +## Inspect the output files + +The files generated from the `dry-run` command represent the equivalent Actions workflow for the provided Bamboo pipeline. + +## Next lab + +[Use the migrate command to open a PR with the supplied workflow.](4-migrate.md) diff --git a/bamboo/4-migrate.md b/bamboo/4-migrate.md new file mode 100644 index 0000000..cb2dc73 --- /dev/null +++ b/bamboo/4-migrate.md @@ -0,0 +1,53 @@ +# Perform a production migration of a Bamboo plan + +In this lab, you will use the `migrate` command to convert a Bamboo plan 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). + +## Performing a migration + +Answer the following questions before running a `migrate` command: + +1. Where do you want to store the logs? + - __tmp/migrate__ + +2. 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. + + ``` + export TARGET_URL= + ``` + +3. What is the source + +### Steps + +1. Run the following `migrate` command in your codespace terminal: + + ```bash + $ gh actions-importer migrate bamboo build --target-url $TARGET_URL --output-dir tmp/migrate --source-file-path $SOURCE_FILE_PATH + ``` + +2. The command will write the URL to the pull request that is created when the command succeeds. + + +3. Open the generated pull request in a new browser tab. + +### Inspect the pull request + +The pull request contains a list of manual steps to complete. + +Inspect the "Files changed" in this pull request and see the converted workflow. Any additional changes or code reviews that were needed should be done in this pull request. + +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 Bamboo build plan to Actions! + +### Next lab + +This concludes all labs for migrating a Bamboo plan Actions with GitHub Actions Importer! diff --git a/bamboo/bootstrap/config.yml b/bamboo/bootstrap/config.yml index 16e98e2..5efafa5 100644 --- a/bamboo/bootstrap/config.yml +++ b/bamboo/bootstrap/config.yml @@ -1,3 +1,3 @@ source_files: - - repository_slug: NEW/ROCKET + - repository_slug: SAM/SAMPLE path: bamboo/bootstrap/source_files/bamboo/bamboo.yml diff --git a/bamboo/bootstrap/source_files/bamboo/bamboo.yml b/bamboo/bootstrap/source_files/bamboo/bamboo.yml index 9d3e4ef..8f5356c 100644 --- a/bamboo/bootstrap/source_files/bamboo/bamboo.yml +++ b/bamboo/bootstrap/source_files/bamboo/bamboo.yml @@ -1,29 +1,61 @@ --- version: 2 +plan: + project-key: SAM + key: SAMPLE + name: Sample Plan +stages: +- Build the rocket stage: + manual: false + final: false + jobs: + - Build +Build: + key: JOB1 + tasks: + - checkout: + force-clean-build: false + - script: + interpreter: SHELL + scripts: + - |- + mkdir -p falcon/red + echo wings > falcon/red/wings + sleep 1 + echo 'Built it' + artifacts: + - name: Red rocket built + pattern: falcon/red/wings + shared: true + required: true + artifact-subscriptions: [] variables: global_variable: global_variable_value plan_variable_override: plan_variable_overrid - -plan: - project-key: NEW - key: ROCKET - name: Build the rockets - -# List of plan's stages and jobs -stages: - - Build the rocket stage: - - Build - -#Job definition -Build: - tasks: - - script: - - mkdir -p falcon/red - - echo wings > falcon/red/wings - - sleep 1 - - echo 'Built it' - # Job's artifacts. Artifacts are shared by default. - artifacts: - - name: Red rocket built - pattern: falcon/red/wings +repositories: +- yaml-test-repo: + scope: global +triggers: +- polling: + period: '180' +branches: + create: for-new-branch + delete: + after-deleted-days: 1 + after-inactive-days: 30 + link-to-jira: true +notifications: +- events: + - plan-failed + recipients: + - responsible + - watchers +labels: [] +dependencies: + require-all-stages-passing: false + enabled-for-branches: true + block-strategy: none + plans: [] +other: + concurrent-build-plugin: system-default diff --git a/bamboo/readme.md b/bamboo/readme.md new file mode 100644 index 0000000..65ef7d8 --- /dev/null +++ b/bamboo/readme.md @@ -0,0 +1,69 @@ +# Bamboo Server migrations powered by GitHub Actions Importer + +The instructions below will guide you through configuring a GitHub Codespace environment to learn how to use GitHub Actions Importer to migrate Bamboo pipelines to GitHub Actions. + +These steps **must** be completed prior to starting other labs. + +## Create your own repository for these labs + +- Ensure that you have created a repository using the [actions/importer-labs](https://github.com/actions/importer-labs) as a template. + +## Configure your codespace + +1. Start a new codespace. + + - 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. + +2. Verify the GitHub Actions Importer CLI is installed and working. More information on the GitHub Actions Importer extension for the official GitHub CLI can be found [here](https://github.com/github/gh-actions-importer). + + - Run the following command in the codespace's terminal: + + ```bash + gh actions-importer version + ``` + + - Verify the output is similar to below. + + ```console + $ gh actions-importer version + gh actions-importer github/gh-actions-importer v1.3.4 + actions-importer/cli:latest v1.3.20618 + ``` + + - If `gh actions-importer version` did not produce similar output, refer to the [troubleshooting section](#troubleshoot-the-github-actions-importer-cli). + +## Labs for Bamboo + +Perform the following labs to learn more about Actions migrations with GitHub Actions Importer: + +1. [Configure credentials for GitHub Actions Importer](1-configure.md) +2. [Perform an audit of a Bamboo server](2-audit.md) +3. [Perform a dry-run migration of a Bamboo pipeline](3-dry-run.md) +4. [Perform a production migration of a Bamboo pipeline](4-migrate.md) + +## Troubleshoot the GitHub Actions Importer CLI + +The CLI extension for GitHub Actions Importer can be manually installed by following these steps: + +- Verify you are in the codespace terminal +- Run this command from within the codespace terminal: + + ```bash + gh extension install github/gh-actions-importer + ``` + +- Verify the result of the install contains: + + ```console + $ gh extension install github/gh-actions-importer + ✓ Installed extension github/gh-actions-importer + ``` + +- Verify the GitHub Actions Importer CLI extension is installed and working by running the following command from the codespace terminal: + + ```bash + gh actions-importer version + ``` diff --git a/readme.md b/readme.md index 52ae8c3..87aaaed 100644 --- a/readme.md +++ b/readme.md @@ -9,6 +9,7 @@ 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. Choose where to start. There are currently learning paths for: - [Migrating from Azure DevOps to GitHub Actions](/azure_devops/readme.md) + - [Migrating from Bamboo to GitHub Actions](/bamboo/readme.md) - [Migrating from Bitbucket to GitHub Actions](/bitbucket/readme.md) - [Migrating from CircleCI to GitHub Actions](/circle_ci/readme.md) - [Migrating from GitLab to GitHub Actions](/gitlab/readme.md) From 4af988afe7cddabe89f03e153d374b8f49985214 Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Tue, 12 Sep 2023 11:41:59 -0600 Subject: [PATCH 03/18] Remove exports from dry-run --- bamboo/3-dry-run.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/bamboo/3-dry-run.md b/bamboo/3-dry-run.md index d262203..5709e2d 100644 --- a/bamboo/3-dry-run.md +++ b/bamboo/3-dry-run.md @@ -14,18 +14,14 @@ You will be performing a dry run against a single Bamboo pipeline. Answer the fo 1. What is the planslug of the pipeline you want to convert? - ``` - export PLAN_SLUG=MARS-ROCKET - ``` + - __MARS-ROCKET__ 2. Where do you want to store the result? - __tmp/dry-run__. This can be any path within the working directory from which GitHub Actions Importer commands are executed. 3. Which file would you like to conver? - ``` - export SOURCE_FILE_PATH=bamboo/bootstrap/source_files/bamboo/bamboo.yml - ``` + - __bamboo/bootstrap/source_files/bamboo/bamboo.yml__ 4. Are you converting a build or deployment plan? - The supplied configuration is a build plan. @@ -36,7 +32,7 @@ You will be performing a dry run against a single Bamboo pipeline. Answer the fo 2. Run the following command from the root directory: ```bash - gh actions-importer dry-run bamboo build --source-file-path $SOURCE_FILE_PATH -p $PLAN_SLUG--output-dir tmp/dry-run + gh actions-importer dry-run bamboo build --source-file-path bamboo/bootstrap/source_files/bamboo/bamboo.yml -p MARS-ROCKET --output-dir tmp/dry-run ``` 3. The command will list all the files written to disk when the command succeeds. From 597c53896cfd893acf2d2aa18f345d9ee4c41851 Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Tue, 12 Sep 2023 11:43:33 -0600 Subject: [PATCH 04/18] Remove export from 4-migrate.md --- bamboo/4-migrate.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/bamboo/4-migrate.md b/bamboo/4-migrate.md index cb2dc73..dd721f0 100644 --- a/bamboo/4-migrate.md +++ b/bamboo/4-migrate.md @@ -19,10 +19,6 @@ Answer the following questions before running a `migrate` command: 2. 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. - ``` - export TARGET_URL= - ``` - 3. What is the source ### Steps @@ -30,7 +26,7 @@ Answer the following questions before running a `migrate` command: 1. Run the following `migrate` command in your codespace terminal: ```bash - $ gh actions-importer migrate bamboo build --target-url $TARGET_URL --output-dir tmp/migrate --source-file-path $SOURCE_FILE_PATH + $ gh actions-importer migrate bamboo build --target-url --output-dir tmp/migrate --source-file-path bamboo/bootstrap/source_files/bamboo/bamboo.yml ``` 2. The command will write the URL to the pull request that is created when the command succeeds. From f9475dde2f187abde45922a823e317af8d0520cf Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Wed, 13 Sep 2023 11:30:21 -0600 Subject: [PATCH 05/18] Add a second pipeline per recs --- bamboo/bootstrap/config.yml | 3 + .../bootstrap/source_files/bonnie/source.yml | 164 ++++++++++++++++++ 2 files changed, 167 insertions(+) create mode 100644 bamboo/bootstrap/source_files/bonnie/source.yml diff --git a/bamboo/bootstrap/config.yml b/bamboo/bootstrap/config.yml index 5efafa5..e5dba84 100644 --- a/bamboo/bootstrap/config.yml +++ b/bamboo/bootstrap/config.yml @@ -1,3 +1,6 @@ source_files: - repository_slug: SAM/SAMPLE path: bamboo/bootstrap/source_files/bamboo/bamboo.yml + - repository_slug: DEMO/MAR + path: bamboo/bootstrap/source_files/bonnie/source.yml + diff --git a/bamboo/bootstrap/source_files/bonnie/source.yml b/bamboo/bootstrap/source_files/bonnie/source.yml new file mode 100644 index 0000000..155f6ed --- /dev/null +++ b/bamboo/bootstrap/source_files/bonnie/source.yml @@ -0,0 +1,164 @@ +--- +version: 2 +plan: + project-key: DEMO + key: MAR + name: Bonnie +stages: +- Git Fun: + description: All the git things + manual: false + final: false + jobs: + - All The Git +- Run tests: + manual: false + final: false + jobs: + - Integration tests + - Unit tests +- Deploy: + manual: true + final: false + jobs: + - Deploy +- Cleanup: + manual: false + final: true + jobs: + - Cleanup +All The Git: + key: GIT + description: All things GIT! + tasks: + - checkout: + force-clean-build: false + description: Checkout Repo + - script: + interpreter: SHELL + scripts: + - |- + echo $RANDOM > random.txt + cat random.txt + description: Write some nonsense to a file + artifact-subscriptions: [] + source_plan: DEMO-MAR + enabled: true +Integration tests: + key: IT + tasks: + - checkout: + force-clean-build: true + - script: + interpreter: SHELL + scripts: + - touch report.xml + - any-task: + plugin-key: com.atlassian.bamboo.plugins.bamboo-nodejs-plugin:task.builder.npm + configuration: + isolatedCache: 'false' + runtime: alt + command: install + final-tasks: + - any-task: + plugin-key: com.atlassian.bamboo.plugins.bamboo-nodejs-plugin:task.reporter.mocha + configuration: + testPattern: mocha-1.json, mocha-2.json + workingSubDirectory: "/this_is_a_subdir" + pickupOutdatedFiles: 'true' + artifact-subscriptions: [] + source_plan: DEMO-MAR + enabled: true +Unit tests: + key: UT + tasks: + - checkout: + force-clean-build: false + - script: + interpreter: SHELL + scripts: + - touch report.xml + - test-parser: + type: junit + ignore-time: true + test-results: "**/test-reports/*.xml" + conditions: + - variable: + exists: test + description: this is not a final task + artifact-subscriptions: [] + source_plan: DEMO-MAR + enabled: true +Deploy: + key: JOB1 + docker: + image: oracle + volumes: + "/home/user": "/home/user" + "/opt": "/opt" + docker-run-arguments: [] + tasks: + - checkout: + force-clean-build: false + - any-task: + plugin-key: com.atlassian.bamboo.plugins.atlassian-bamboo-plugin-aws-codedeploy:task.aws.codeDeploy + configuration: + deploymentTimeout: '15' + deploymentGroup: DgpECS-user_cluster-alt_service + credentialsId: '10092545' + region: US_WEST_1 + applicationName: AppECS-user_cluster-alt_service + s3Bucket: elasticbeanstalk-us-west-1-778232459879 + workingSubDirectory: this_is_a_subdir + conditions: + - variable: + exists: test + artifact-subscriptions: [] + source_plan: DEMO-MAR + enabled: true +Cleanup: + key: CLEAN + tasks: + - checkout: + force-clean-build: false + artifact-subscriptions: [] + source_plan: DEMO-MAR + enabled: true +variables: + password: BAMSCRT@0@0@V2tJ1qmyHu7Rpm0N/jQ6k2552ul9JTDCUVI0r6sMo9k= + username: admin +repositories: +- User Actions Playground: + type: git + url: git@github.com:User/actions-playground.git + branch: main + shared-credentials: User Bamboo SSH Key + command-timeout-minutes: '180' + lfs: false + verbose-logs: false + use-shallow-clones: false + cache-on-agents: true + submodules: false + ssh-key-applies-to-submodules: true + fetch-all: false +triggers: +- cron: + expression: 0 10,44 14 ? 3 WED +branches: + create: manually + delete: never + link-to-jira: false +notifications: +- events: + - plan-failed + recipients: + - responsible + - watchers +labels: [] +dependencies: + require-all-stages-passing: false + enabled-for-branches: true + block-strategy: none + plans: [] +other: + concurrent-build-plugin: system-default From 6ee6678cbfa023eb26decfff7ab9e22d3ff78fe4 Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Wed, 13 Sep 2023 18:53:02 -0600 Subject: [PATCH 06/18] Update bamboo/3-dry-run.md Co-authored-by: j-dunham --- bamboo/3-dry-run.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bamboo/3-dry-run.md b/bamboo/3-dry-run.md index 5709e2d..40062b1 100644 --- a/bamboo/3-dry-run.md +++ b/bamboo/3-dry-run.md @@ -19,7 +19,7 @@ You will be performing a dry run against a single Bamboo pipeline. Answer the fo 2. Where do you want to store the result? - __tmp/dry-run__. This can be any path within the working directory from which GitHub Actions Importer commands are executed. -3. Which file would you like to conver? +3. Which file would you like to convert? - __bamboo/bootstrap/source_files/bamboo/bamboo.yml__ From cdd19b7f9259286a26416a305f0aaaa6901780d0 Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Wed, 13 Sep 2023 18:53:10 -0600 Subject: [PATCH 07/18] Update bamboo/3-dry-run.md Co-authored-by: j-dunham --- bamboo/3-dry-run.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bamboo/3-dry-run.md b/bamboo/3-dry-run.md index 40062b1..d68aae6 100644 --- a/bamboo/3-dry-run.md +++ b/bamboo/3-dry-run.md @@ -12,7 +12,7 @@ In this lab you will use the `dry-run` command to convert a Bamboo build plan to You will be performing a dry run against a single Bamboo pipeline. Answer the following questions before running this command: -1. What is the planslug of the pipeline you want to convert? +1. What is the plan slug of the pipeline you want to convert? - __MARS-ROCKET__ From 25fad773dc9151ab9924dc367d84c8c23655108b Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Wed, 13 Sep 2023 18:59:19 -0600 Subject: [PATCH 08/18] Update bamboo/3-dry-run.md Co-authored-by: j-dunham --- bamboo/3-dry-run.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bamboo/3-dry-run.md b/bamboo/3-dry-run.md index d68aae6..5e5e447 100644 --- a/bamboo/3-dry-run.md +++ b/bamboo/3-dry-run.md @@ -43,7 +43,7 @@ You will be performing a dry run against a single Bamboo pipeline. Answer the fo 4. View the converted workflow: - Find `tmp/dry-run/test_pipeline/.github/workflows` in the file explorer pane in your codespace. - - Click `test_pipeline.yml` to open. + - Click `sample_plan.yml` to open. ## Inspect the output files From 4481eef856a0731b5bebfd5b91b4839ed1885839 Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Thu, 14 Sep 2023 11:27:40 -0600 Subject: [PATCH 09/18] Add the output from the dry-run --- bamboo/3-dry-run.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/bamboo/3-dry-run.md b/bamboo/3-dry-run.md index 5e5e447..74ccb8b 100644 --- a/bamboo/3-dry-run.md +++ b/bamboo/3-dry-run.md @@ -38,11 +38,13 @@ You will be performing a dry run against a single Bamboo pipeline. Answer the fo 3. The command will list all the files written to disk when the command succeeds. ```console - $ gh actions-importer dry-run bamboo build + Logs: 'tmp/dry-run/log/valet.log' + Output file(s): + tmp/dry-run/build/mars/sample_plan/.github/workflows/sample_plan.yml ``` 4. View the converted workflow: - - Find `tmp/dry-run/test_pipeline/.github/workflows` in the file explorer pane in your codespace. + - Find `tmp/dry-run/build/mars/sample_plan/.github/workflows` in the file explorer pane in your codespace. - Click `sample_plan.yml` to open. ## Inspect the output files From caa5e9a3f8b72f911d52cd9d81ee7da9c6bc0782 Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Thu, 14 Sep 2023 12:07:31 -0600 Subject: [PATCH 10/18] Re-run audit with multiple files. Update --- bamboo/2-audit.md | 53 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 39 insertions(+), 14 deletions(-) diff --git a/bamboo/2-audit.md b/bamboo/2-audit.md index b4405f5..855ebee 100644 --- a/bamboo/2-audit.md +++ b/bamboo/2-audit.md @@ -49,9 +49,9 @@ The pipeline summary section contains high level statistics regarding the conver ```md ## Pipelines -Total: **1** +Total: **2** -- Successful: **1 (100%)** +- Successful: **2 (100%)** - Partially successful: **0 (0%)** - Unsupported: **0 (0%)** - Failed: **0 (0%)** @@ -73,9 +73,9 @@ The "Job types" section will summarize which types of pipelines are being used a ``` ### Job types -Supported: **1 (100%)** +Supported: **2 (100%)** -- build: **1** +- build: **2** ``` #### Build steps @@ -85,18 +85,25 @@ The build steps summary section presents an overview of the individual build ste ```md ### Build steps -Total: **2** +Total: **15** -Known: **2 (100%)** +Known: **15 (100%)** -- script: **1** -- checkout: **1** +- checkout: **6** +- script: **4** +- any-task/plugin-key/com.atlassian.bamboo.plugins.atlassian-bamboo-plugin-aws-codedeploy:task.aws.codeDeploy: **2** +- any-task/plugin-key/com.atlassian.bamboo.plugins.bamboo-nodejs-plugin:task.reporter.mocha: **1** +- test-parser/type/junit: **1** +- any-task/plugin-key/com.atlassian.bamboo.plugins.bamboo-nodejs-plugin:task.builder.npm: **1** -Actions: **3** +Actions: **17** +- actions/checkout@v3.5.0: **6** +- run: **6** +- EnricoMi/publish-unit-test-result-action@v2.9.0: **2** +- actions/setup-node@v3.7.0: **1** +- aws-actions/configure-aws-credentials@v2.2.0: **1** - actions/upload-artifact@v3.1.1: **1** -- run: **1** -- actions/checkout@v3.5.0: **1** ``` Here are some key terms in the "Build steps" section: @@ -116,6 +123,18 @@ There is an equivalent breakdown of build triggers, environment variables, and o 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. +``` +### Manual tasks + +Total: **3** + +Secrets: **3** + +- `${{ secrets.AWS_ACCESS_KEY_ID }}`: **1** +- `${{ secrets.AWS_SECRET_ACCESS_KEY }}`: **1** +- `${{ secrets.AWS_S3_BUCKET_KEY }}`: **1** +``` + 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. @@ -139,11 +158,17 @@ Each pipeline will have a variety of files written that include: ```csv Pipeline,Action,File path - mars/rocket,actions/checkout@v3.5.0,tmp/audit/build/mars/rocket/.github/workflows/rocket.yml - mars/rocket,actions/upload-artifact@v3.1.1,tmp/audit/build/mars/rocket/.github/workflows/rocket.yml + sam/sample,actions/checkout@v3.5.0,tmp/audit/build/sam/sample/.github/workflows/sample.yml + sam/sample,actions/upload-artifact@v3.1.1,tmp/audit/build/sam/sample/.github/workflows/sample.yml + demo/mar,actions/checkout@v3.5.0,tmp/audit/build/demo/mar/.github/workflows/mar.yml + demo/mar,actions/setup-node@v3.7.0,tmp/audit/build/demo/mar/.github/workflows/mar.yml + demo/mar,EnricoMi/publish-unit-test-result-action@v2.9.0,tmp/audit/build/demo/mar/.github/workflows/mar.yml + demo/mar,aws-actions/configure-aws-credentials@v2.2.0,tmp/audit/build/demo/mar/.github/workflows/mar.yml Pipeline,Secret,File path - + demo/mar,${{ secrets.AWS_ACCESS_KEY_ID }},tmp/audit/build/demo/mar/.github/workflows/mar.yml + demo/mar,${{ secrets.AWS_SECRET_ACCESS_KEY }},tmp/audit/build/demo/mar/.github/workflows/mar.yml + demo/mar,${{ secrets.AWS_S3_BUCKET_KEY }},tmp/audit/build/demo/mar/.github/workflows/mar.yml Pipeline,Runner,File path ``` From f1306b3ed30f89ddec93f28a9f3369eb26150fb2 Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Fri, 15 Sep 2023 09:27:57 -0600 Subject: [PATCH 11/18] Update bamboo/2-audit.md Co-authored-by: Ethan Dennis --- bamboo/2-audit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bamboo/2-audit.md b/bamboo/2-audit.md index 855ebee..9fd86e9 100644 --- a/bamboo/2-audit.md +++ b/bamboo/2-audit.md @@ -1,6 +1,6 @@ # Perform an audit of an Bamboo plan -In this lab, you will use the `audit` command to get a high-level view of all pipelines in an Bamboo config file. This lab uses local config files to demonstrate the actions-importer functionality. +In this lab, you will use the `audit` command to get a high-level view of all pipelines in a Bamboo config file. This lab uses local config files to demonstrate the actions-importer functionality. The `audit` command will perform the following steps: From 7517b9070da1ff1d86193f5a5ac5a1b9e9b547af Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Fri, 15 Sep 2023 09:28:05 -0600 Subject: [PATCH 12/18] Update bamboo/2-audit.md Co-authored-by: Ethan Dennis --- bamboo/2-audit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bamboo/2-audit.md b/bamboo/2-audit.md index 9fd86e9..a6222d5 100644 --- a/bamboo/2-audit.md +++ b/bamboo/2-audit.md @@ -10,7 +10,7 @@ The `audit` command will perform the following steps: ## Prerequisites -1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment and bootstrap an Bamboo project. +1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment and bootstrap a Bamboo project. 2. Completed the [configure lab](./1-configure.md#configuring-credentials). ## Perform an audit From f1e83f223964014374e0ce847fa888b6baa83594 Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Fri, 15 Sep 2023 11:48:25 -0600 Subject: [PATCH 13/18] Add cautionary "notes" --- bamboo/2-audit.md | 1 + bamboo/3-dry-run.md | 1 + bamboo/4-migrate.md | 2 ++ 3 files changed, 4 insertions(+) diff --git a/bamboo/2-audit.md b/bamboo/2-audit.md index a6222d5..207fe74 100644 --- a/bamboo/2-audit.md +++ b/bamboo/2-audit.md @@ -31,6 +31,7 @@ You will audit the configured Bamboo pipelines. Answer the following questions b ```bash gh actions-importer audit bamboo -o tmp/audit --config-file-path bamboo/bootstrap/config.yml ``` + > Note: The `--config-file-path` option is not required and is used throughout these labs to convert files that are stored locally for this lab. When performing a migration on your own Bamboo Server, `config-file-path` can be omitted and GitHub Actions Importer will programmatically fetch pipelines using the Bambooo REST APIs. 3. The command will list all the files written to disk in green when the command succeeds. diff --git a/bamboo/3-dry-run.md b/bamboo/3-dry-run.md index 74ccb8b..8b84fa6 100644 --- a/bamboo/3-dry-run.md +++ b/bamboo/3-dry-run.md @@ -34,6 +34,7 @@ You will be performing a dry run against a single Bamboo pipeline. Answer the fo ```bash gh actions-importer dry-run bamboo build --source-file-path bamboo/bootstrap/source_files/bamboo/bamboo.yml -p MARS-ROCKET --output-dir tmp/dry-run ``` + > Note: The `--source-file-path` option is not required and is used throughout this lab to convert a pipeline that is stored locally. This can be omitted and GitHub Actions Importer will programmatically fetch pipelines using the Bamboo REST APIs 3. The command will list all the files written to disk when the command succeeds. diff --git a/bamboo/4-migrate.md b/bamboo/4-migrate.md index dd721f0..a4d2883 100644 --- a/bamboo/4-migrate.md +++ b/bamboo/4-migrate.md @@ -29,6 +29,8 @@ Answer the following questions before running a `migrate` command: $ gh actions-importer migrate bamboo build --target-url --output-dir tmp/migrate --source-file-path bamboo/bootstrap/source_files/bamboo/bamboo.yml ``` + Note: The `--source-file-path` option is not required and is used throughout this lab to convert files that are stored locally. This can be omitted and GitHub Actions Importer will programmatically fetch pipeline definitions using the Bamboo REST APIs. + 2. The command will write the URL to the pull request that is created when the command succeeds. From 33a0d421a1dac81ddfced29221c4d4aefd99e33f Mon Sep 17 00:00:00 2001 From: Bree Dodd <40243716+breeldo@users.noreply.github.com> Date: Fri, 15 Sep 2023 16:38:57 -0600 Subject: [PATCH 14/18] Add Bamboo Forecast & Custom Transformers --- bamboo/2-audit.md | 2 +- bamboo/3-forecast.md | 102 ++++ bamboo/{3-dry-run.md => 4-dry-run.md} | 2 +- bamboo/5-custom-transformers.md | 186 ++++++++ bamboo/{4-migrate.md => 6-migrate.md} | 0 .../source_files/09-15-2023-16-30_jobs_0.json | 442 ++++++++++++++++++ .../bootstrap/source_files/custom/bamboo.yml | 68 +++ bamboo/readme.md | 10 +- bitbucket/3-forecast.md | 4 +- 9 files changed, 809 insertions(+), 7 deletions(-) create mode 100644 bamboo/3-forecast.md rename bamboo/{3-dry-run.md => 4-dry-run.md} (95%) create mode 100644 bamboo/5-custom-transformers.md rename bamboo/{4-migrate.md => 6-migrate.md} (100%) create mode 100644 bamboo/bootstrap/source_files/09-15-2023-16-30_jobs_0.json create mode 100644 bamboo/bootstrap/source_files/custom/bamboo.yml diff --git a/bamboo/2-audit.md b/bamboo/2-audit.md index 207fe74..e3d3f79 100644 --- a/bamboo/2-audit.md +++ b/bamboo/2-audit.md @@ -183,4 +183,4 @@ The contents of this file can be useful in answering questions similar to the fo ### Next lab -[Perform a dry run of a individual pipeline](3-dry-run.md) +[Forecast potential build runner usage](3-forecast.md) diff --git a/bamboo/3-forecast.md b/bamboo/3-forecast.md new file mode 100644 index 0000000..bbcf2f6 --- /dev/null +++ b/bamboo/3-forecast.md @@ -0,0 +1,102 @@ +# 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 plan runs in Bamboo. + +## 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 workspace do you want to run the forecast for? + - **actions-importer** +2. What is the date you want to start forecasting from? + - **2023-08-01**. By default, the value is set to one week ago, but it's recommended that you choose a start date that provides a representative view of typical usage. +3. Where do you want to store the results? + - **tmp/forecast** + +### Steps + +1. Navigate to your codespace terminal +2. Run the following command from the root directory: + + ```bash + gh actions-importer forecast bamboo --start-date 2023-08-01 --output-dir tmp/forecast --source-file-path bamboo/**/source_files/*.json + ``` + > Note: The `--source-file-path` option is not required and is used throughout this lab to convert files that are stored locally. This can be omitted and GitHub Actions Importer will programmatically fetch historical pipeline runs using the Bamboo REST APIs. +3. The command will list all the files written to disk when the command succeeds. + ```console + Logs: 'tmp/forecast/log/valet-20230915-223223.log' + Forecasting 'https://.com' + Output file(s): + tmp/forecast/forecast_report.md + ``` +## Review the forecast report +The forecast report, logs, and completed job data will be located within the `tmp/forecast` 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: **40** +- Pipeline count: **4** + +- Execution time + + - Total: **64 minutes** + - Median: **1 minutes** + - P90: **4 minutes** + - Min: **0 minutes** + - Max: **4 minutes** + +- Queue time + + - Median: **0 minutes** + - P90: **2 minutes** + - Min: **0 minutes** + - Max: **2 minutes** + +- Concurrent jobs + + - Median: **0** + - P90: **0** + - Min: **0** + - Max: **3** +``` + +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. +- `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 by hosted and self-hosted runners. +## Forecasting multiple providers +You can examine the available options for the `forecast` command by running `gh actions-importer forecast --help`. When you do this you will see the `--source-file-path` option: +```console +$ gh actions-importer forecast -h +Options: + --source-file-path (REQUIRED) The file path(s) to existing jobs data. + -o, --output-dir (REQUIRED) The location for any output files. + --start-date The start date of the forecast analysis in YYYY-MM-DD format. [default: 9/12/2022 12:42:39 PM] + --time-slice The time slice in seconds to use for computing concurrency metrics. [default: 60] + --credentials-file The file containing the credentials to use. + --no-telemetry Boolean value to disallow telemetry. + --no-ssl-verify Disable ssl certificate verification. + --no-http-cache Disable caching of http responses. + -?, -h, --help Show help and usage information +``` +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`). +Below is a example command that would generate a report for all files matching `tmp/**/jobs/*.json`: +```bash +gh actions-importer forecast --source-file-path tmp/**/jobs/*.json --output-dir tmp/forecast-combined +``` +## Next steps +[Perform a dry-run migration of a Bamboo pipeline](4-dry-run.md) diff --git a/bamboo/3-dry-run.md b/bamboo/4-dry-run.md similarity index 95% rename from bamboo/3-dry-run.md rename to bamboo/4-dry-run.md index 8b84fa6..aa6e89c 100644 --- a/bamboo/3-dry-run.md +++ b/bamboo/4-dry-run.md @@ -54,4 +54,4 @@ The files generated from the `dry-run` command represent the equivalent Actions ## Next lab -[Use the migrate command to open a PR with the supplied workflow.](4-migrate.md) +[Use custom transformers to customize GitHub Actions Importer's behavior](5-custom-transformers.md) diff --git a/bamboo/5-custom-transformers.md b/bamboo/5-custom-transformers.md new file mode 100644 index 0000000..abbbd0f --- /dev/null +++ b/bamboo/5-custom-transformers.md @@ -0,0 +1,186 @@ +# 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: + +1. Convert items that are not automatically converted. +2. Convert items that were automatically converted using different actions. +3. Convert environment variable values differently. +4. Convert references to runners to use a different runner name in GitHub Actions. + +## 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](./4-dry-run.md). + +## 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: + +```bash +gh actions-importer dry-run bamboo build --output-dir tmp/custom-dry-run --plan-slug DEMO-MAR --source-file-path bamboo/bootstrap/source_files/custom/bamboo.yml +``` + +The converted workflow generated by the above command can be seen below: + +
+ Converted workflow 👇 + +```yaml +name: demo/sample_plan +on: +# # The shortest interval you can run scheduled workflows is once every 5 minutes. +# period: '180' +jobs: + Custom-Dry-Run-Build: + runs-on: + - self-hosted + - bamboo-runner + steps: + - uses: actions/checkout@v3.5.0 + with: + clean: false + - run: |- + mkdir -p falcon/red + echo wings > falcon/red/wings + sleep 1 + echo 'Built it' +# # This item has no matching transformer +# - any-task/plugin-key/com.atlassian.bamboo.plugins.builder.unknowncache: +# any-task: +# plugin-key: com.atlassian.bamboo.plugins.builder.unknowncache +# configuration: +# key: cache_key +# path: falcon/red/wings + - uses: actions/upload-artifact@v3.1.1 + with: + name: FOO-BAR_Red rocket built + path: falcon/red/wings + if-no-files-found: error +``` + +
+ +_Note_: You can refer to the previous [lab](./4-dry-run.md) to learn about the fundamentals of the `dry-run` command. + +## Custom transformers for an unknown step + +The converted workflow contains a `any-task/plugin-key/com.atlassian.bamboo.plugins.builder.unknowncache` step that was not automatically converted. Let's write a custom transformer to handle this unknown task! + +Let's answer the following questions before proceeding to write a custom transformer. + +1) What is the "identifier" of the step to customize? This should be the identifier from the comment in the workflow without the version, or in other words the name untransformed step. + - __any-task/plugin-key/com.atlassian.bamboo.plugins.builder.unknown__ + +2) What is the desired Actions syntax to use instead? + - Upon conducting some research, you've discovered that the [Actions Cache](https://github.com/marketplace/actions/cache) action in the marketplace offer comparable functionality. + + ```yaml + - uses: actions/cache/save@v3 + with: + path: + key: + ``` + + Now you can begin to write the custom transformer. Custom transformers use a DSL built on top of Ruby and should be defined in a file with the `.rb` file extension. You can create this file by running the following command in your codespace terminal: + + ```bash + touch transformers.rb && code transformers.rb + ``` + + Next, you will define a `transform` method for the `any-task/plugin-key/com.atlassian.bamboo.plugins.builder.unknowncache` identifier by adding the following code to `transformers.rb`: + + ```ruby + transform "any-task/plugin-key/com.atlassian.bamboo.plugins.builder.unknowncache" do |item| + [ + { + "uses" => "azure/cache/save@v3", + "with" => { + "path" => item["configuration"]["path"], + "key" => item["configuration"]["key"] + } + } + ] + end + ``` + +This method can use any valid Ruby syntax and should return a `Hash` or `Array` 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 Bamboo. The Bamboo task configuration can be accessed in the `item` parameter via `item["configuration"][""]`. + +```yaml +plugin-key: com.atlassian.bamboo.plugins.builder.unknowncache +configuration: + key: cache_key + path: falcon/red/wings +``` + +To access the values of the `key` and `path` information in the transformer, we are using `item["configuration"]["key"]` and `item["configuration"]["path"]`. + +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: + +```bash +gh actions-importer dry-run bamboo build --output-dir tmp/custom-dry-run --plan-slug DEMO-MAR --source-file-path bamboo/bootstrap/source_files/custom/bamboo.yml --custom-transformers transformers.rb +``` + +The converted workflow that is generated by the above command will now use the custom logic for the `unknowncache` step. + +## Custom transformers for runners + +Next, we will use a custom transformers to dictate which runners the converted workflows should use. To do this, answer the following questions: + +1. What is the label of the runner in Bamboo to change? + - __bamboo-runner__ + +2. What is the label of the runner in GitHub Actions to use instead? + - __some-other-runner__ + +With these questions answered, you can add the following code to the `transformers.rb` file: + +```ruby +runner "bamboo-runner", "some-other-runner" +``` + +In this example, the first parameter to the `runner` method is the runner label in Bitbucket and the second is the new runner label to use in GitHub Actions. + +Now you can perform another `dry-run` command with the `--custom-transformers` CLI option. When you open the converted workflow the `runs-on` statement will use the customized runner label: + +```bash +gh actions-importer dry-run bamboo build --output-dir tmp/custom-dry-run --plan-slug DEMO-MAR --source-file-path bamboo/bootstrap/source_files/custom/bamboo.yml --custom-transformers transformers.rb +``` +> Note: we are using a different pipeline than before that defines a `runs-on` tag with the target label. + +```diff +runs-on: +- - bamboo-runner ++ - some-other-runner +``` + +At this point the file contents of `transformers.rb` should match this: + +
+ Custom transformers 👇 + +```ruby +runner "bamboo-runner", "some-other-runner" + +transform "any-task/plugin-key/com.atlassian.bamboo.plugins.builder.unknowncache" do |item| + [ + { + "uses" => "azure/cache/save@v3", + "with" => { + "path" => item["configuration"]["path"], + "key" => item["configuration"]["key"] + } + } + ] +end +``` + +
+ +That's it. Congratulations, you have overridden GitHub Actions Importer's default behavior by customizing the conversion of: + +- Unknown steps +- Runners + +## Next lab +[Perform a production migration of a Bamboo pipeline](6-migrate.md) diff --git a/bamboo/4-migrate.md b/bamboo/6-migrate.md similarity index 100% rename from bamboo/4-migrate.md rename to bamboo/6-migrate.md diff --git a/bamboo/bootstrap/source_files/09-15-2023-16-30_jobs_0.json b/bamboo/bootstrap/source_files/09-15-2023-16-30_jobs_0.json new file mode 100644 index 0000000..47768ab --- /dev/null +++ b/bamboo/bootstrap/source_files/09-15-2023-16-30_jobs_0.json @@ -0,0 +1,442 @@ +[ + { + "id": 11043093, + "build_number": 11043093, + "result": "Successful", + "queue_time": "2023-09-15T00:00:00+00:00", + "start_time": "2023-09-15T00:00:00+00:00", + "finish_time": "2023-09-15T00:02:00+00:00", + "definition_id": "FORT-BUIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043078, + "build_number": 11043078, + "result": "Successful", + "queue_time": "2023-09-14T00:00:00+00:00", + "start_time": "2023-09-14T00:00:15+00:00", + "finish_time": "2023-09-14T00:02:15+00:00", + "definition_id": "FORT-BUIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043067, + "build_number": 11043067, + "result": "Successful", + "queue_time": "2023-09-13T00:00:00+00:00", + "start_time": "2023-09-13T00:00:00+00:00", + "finish_time": "2023-09-13T00:02:00+00:00", + "definition_id": "FORT-BUIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043053, + "build_number": 11043053, + "result": "Successful", + "queue_time": "2023-09-12T00:00:00+00:00", + "start_time": "2023-09-12T00:00:15+00:00", + "finish_time": "2023-09-12T00:02:15+00:00", + "definition_id": "FORT-BUIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043037, + "build_number": 11043037, + "result": "Successful", + "queue_time": "2023-09-11T00:00:00+00:00", + "start_time": "2023-09-11T00:00:00+00:00", + "finish_time": "2023-09-11T00:02:00+00:00", + "definition_id": "FORT-BUIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043026, + "build_number": 11043026, + "result": "Successful", + "queue_time": "2023-09-10T00:00:00+00:00", + "start_time": "2023-09-10T00:00:00+00:00", + "finish_time": "2023-09-10T00:02:00+00:00", + "definition_id": "FORT-BUIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043011, + "build_number": 11043011, + "result": "Successful", + "queue_time": "2023-09-09T00:00:00+00:00", + "start_time": "2023-09-09T00:00:00+00:00", + "finish_time": "2023-09-09T00:02:00+00:00", + "definition_id": "FORT-BUIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11042998, + "build_number": 11042998, + "result": "Successful", + "queue_time": "2023-09-08T00:00:00+00:00", + "start_time": "2023-09-08T00:00:15+00:00", + "finish_time": "2023-09-08T00:02:15+00:00", + "definition_id": "FORT-BUIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043102, + "build_number": 11043102, + "result": "Successful", + "queue_time": "2023-09-15T01:00:00+00:00", + "start_time": "2023-09-15T01:00:00+00:00", + "finish_time": "2023-09-15T01:03:20+00:00", + "definition_id": "FORT-RS", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043087, + "build_number": 11043087, + "result": "Successful", + "queue_time": "2023-09-14T01:00:00+00:00", + "start_time": "2023-09-14T01:00:00+00:00", + "finish_time": "2023-09-14T01:03:20+00:00", + "definition_id": "FORT-RS", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043074, + "build_number": 11043074, + "result": "Successful", + "queue_time": "2023-09-13T01:00:00+00:00", + "start_time": "2023-09-13T01:00:00+00:00", + "finish_time": "2023-09-13T01:03:20+00:00", + "definition_id": "FORT-RS", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043061, + "build_number": 11043061, + "result": "Successful", + "queue_time": "2023-09-12T01:00:00+00:00", + "start_time": "2023-09-12T01:00:00+00:00", + "finish_time": "2023-09-12T01:03:20+00:00", + "definition_id": "FORT-RS", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043046, + "build_number": 11043046, + "result": "Successful", + "queue_time": "2023-09-11T01:00:00+00:00", + "start_time": "2023-09-11T01:00:00+00:00", + "finish_time": "2023-09-11T01:03:20+00:00", + "definition_id": "FORT-RS", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043033, + "build_number": 11043033, + "result": "Successful", + "queue_time": "2023-09-10T01:00:00+00:00", + "start_time": "2023-09-10T01:00:00+00:00", + "finish_time": "2023-09-10T01:03:20+00:00", + "definition_id": "FORT-RS", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043020, + "build_number": 11043020, + "result": "Successful", + "queue_time": "2023-09-09T01:00:00+00:00", + "start_time": "2023-09-09T01:00:00+00:00", + "finish_time": "2023-09-09T01:03:20+00:00", + "definition_id": "FORT-RS", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043007, + "build_number": 11043007, + "result": "Successful", + "queue_time": "2023-09-08T01:00:00+00:00", + "start_time": "2023-09-08T01:00:00+00:00", + "finish_time": "2023-09-08T01:03:20+00:00", + "definition_id": "FORT-RS", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043095, + "build_number": 11043095, + "result": "Successful", + "queue_time": "2023-09-15T00:00:00+00:00", + "start_time": "2023-09-15T00:02:00+00:00", + "finish_time": "2023-09-15T00:02:00+00:00", + "definition_id": "PAN-CON", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043080, + "build_number": 11043080, + "result": "Successful", + "queue_time": "2023-09-14T00:00:00+00:00", + "start_time": "2023-09-14T00:02:15+00:00", + "finish_time": "2023-09-14T00:02:15+00:00", + "definition_id": "PAN-CON", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043065, + "build_number": 11043065, + "result": "Successful", + "queue_time": "2023-09-13T00:00:00+00:00", + "start_time": "2023-09-13T00:02:15+00:00", + "finish_time": "2023-09-13T00:02:15+00:00", + "definition_id": "PAN-CON", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043052, + "build_number": 11043052, + "result": "Successful", + "queue_time": "2023-09-12T00:00:00+00:00", + "start_time": "2023-09-12T00:00:00+00:00", + "finish_time": "2023-09-12T00:00:00+00:00", + "definition_id": "PAN-CON", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043044, + "build_number": 11043044, + "result": "Successful", + "queue_time": "2023-09-11T00:00:00+00:00", + "start_time": "2023-09-11T00:02:00+00:00", + "finish_time": "2023-09-11T00:02:00+00:00", + "definition_id": "PAN-CON", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043024, + "build_number": 11043024, + "result": "Successful", + "queue_time": "2023-09-10T00:00:00+00:00", + "start_time": "2023-09-10T00:02:15+00:00", + "finish_time": "2023-09-10T00:02:15+00:00", + "definition_id": "PAN-CON", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043013, + "build_number": 11043013, + "result": "Successful", + "queue_time": "2023-09-09T00:00:00+00:00", + "start_time": "2023-09-09T00:02:15+00:00", + "finish_time": "2023-09-09T00:02:15+00:00", + "definition_id": "PAN-CON", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043000, + "build_number": 11043000, + "result": "Successful", + "queue_time": "2023-09-08T00:00:00+00:00", + "start_time": "2023-09-08T00:02:15+00:00", + "finish_time": "2023-09-08T00:02:15+00:00", + "definition_id": "PAN-CON", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043104, + "build_number": 11043104, + "result": "Successful", + "queue_time": "2023-09-15T21:54:00+00:00", + "start_time": "2023-09-15T21:54:00+00:00", + "finish_time": "2023-09-15T21:54:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043097, + "build_number": 11043097, + "result": "Successful", + "queue_time": "2023-09-15T00:00:00+00:00", + "start_time": "2023-09-15T00:02:00+00:00", + "finish_time": "2023-09-15T00:02:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043091, + "build_number": 11043091, + "result": "Successful", + "queue_time": "2023-09-14T21:54:00+00:00", + "start_time": "2023-09-14T21:54:00+00:00", + "finish_time": "2023-09-14T21:54:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043082, + "build_number": 11043082, + "result": "Successful", + "queue_time": "2023-09-14T00:00:00+00:00", + "start_time": "2023-09-14T00:00:00+00:00", + "finish_time": "2023-09-14T00:00:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043076, + "build_number": 11043076, + "result": "Successful", + "queue_time": "2023-09-13T21:54:00+00:00", + "start_time": "2023-09-13T21:54:00+00:00", + "finish_time": "2023-09-13T21:54:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043069, + "build_number": 11043069, + "result": "Successful", + "queue_time": "2023-09-13T00:00:00+00:00", + "start_time": "2023-09-13T00:02:00+00:00", + "finish_time": "2023-09-13T00:02:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043063, + "build_number": 11043063, + "result": "Successful", + "queue_time": "2023-09-12T21:54:00+00:00", + "start_time": "2023-09-12T21:54:00+00:00", + "finish_time": "2023-09-12T21:54:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043056, + "build_number": 11043056, + "result": "Successful", + "queue_time": "2023-09-12T00:00:00+00:00", + "start_time": "2023-09-12T00:00:00+00:00", + "finish_time": "2023-09-12T00:00:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043050, + "build_number": 11043050, + "result": "Successful", + "queue_time": "2023-09-11T21:54:00+00:00", + "start_time": "2023-09-11T21:54:00+00:00", + "finish_time": "2023-09-11T21:54:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043042, + "build_number": 11043042, + "result": "Successful", + "queue_time": "2023-09-11T00:00:00+00:00", + "start_time": "2023-09-11T00:02:00+00:00", + "finish_time": "2023-09-11T00:02:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043035, + "build_number": 11043035, + "result": "Successful", + "queue_time": "2023-09-10T21:54:00+00:00", + "start_time": "2023-09-10T21:54:00+00:00", + "finish_time": "2023-09-10T21:54:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043028, + "build_number": 11043028, + "result": "Successful", + "queue_time": "2023-09-10T00:00:00+00:00", + "start_time": "2023-09-10T00:02:00+00:00", + "finish_time": "2023-09-10T00:02:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043022, + "build_number": 11043022, + "result": "Successful", + "queue_time": "2023-09-09T21:54:00+00:00", + "start_time": "2023-09-09T21:54:00+00:00", + "finish_time": "2023-09-09T21:54:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043015, + "build_number": 11043015, + "result": "Successful", + "queue_time": "2023-09-09T00:00:00+00:00", + "start_time": "2023-09-09T00:02:00+00:00", + "finish_time": "2023-09-09T00:02:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043009, + "build_number": 11043009, + "result": "Successful", + "queue_time": "2023-09-08T21:54:00+00:00", + "start_time": "2023-09-08T21:54:00+00:00", + "finish_time": "2023-09-08T21:54:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + }, + { + "id": 11043002, + "build_number": 11043002, + "result": "Successful", + "queue_time": "2023-09-08T00:00:00+00:00", + "start_time": "2023-09-08T00:00:00+00:00", + "finish_time": "2023-09-08T00:00:15+00:00", + "definition_id": "PAN-DAIL", + "runner_name": "", + "runner_group": "" + } +] \ No newline at end of file diff --git a/bamboo/bootstrap/source_files/custom/bamboo.yml b/bamboo/bootstrap/source_files/custom/bamboo.yml new file mode 100644 index 0000000..41e534c --- /dev/null +++ b/bamboo/bootstrap/source_files/custom/bamboo.yml @@ -0,0 +1,68 @@ +--- +version: 2 + +plan: + project-key: FOO + key: BAR + name: Sample Plan +stages: +- Custom Dry Run: + manual: false + final: false + jobs: + - Build +Build: + key: JOB1 + requirements: + - bamboo-runner + tasks: + - checkout: + force-clean-build: false + - script: + interpreter: SHELL + scripts: + - |- + mkdir -p falcon/red + echo wings > falcon/red/wings + sleep 1 + echo 'Built it' + - any-task: + plugin-key: com.atlassian.bamboo.plugins.builder.unknowncache + configuration: + key: cache_key + path: falcon/red/wings + artifacts: + - name: Red rocket built + pattern: falcon/red/wings + shared: true + required: true + artifact-subscriptions: [] +variables: + global_variable: global_variable_value + plan_variable_override: plan_variable_override +repositories: +- yaml-test-repo: + scope: global +triggers: +- polling: + period: '180' +branches: + create: for-new-branch + delete: + after-deleted-days: 1 + after-inactive-days: 30 + link-to-jira: true +notifications: +- events: + - plan-failed + recipients: + - responsible + - watchers +labels: [] +dependencies: + require-all-stages-passing: false + enabled-for-branches: true + block-strategy: none + plans: [] +other: + concurrent-build-plugin: system-default diff --git a/bamboo/readme.md b/bamboo/readme.md index 65ef7d8..f2fad19 100644 --- a/bamboo/readme.md +++ b/bamboo/readme.md @@ -40,9 +40,13 @@ These steps **must** be completed prior to starting other labs. Perform the following labs to learn more about Actions migrations with GitHub Actions Importer: 1. [Configure credentials for GitHub Actions Importer](1-configure.md) -2. [Perform an audit of a Bamboo server](2-audit.md) -3. [Perform a dry-run migration of a Bamboo pipeline](3-dry-run.md) -4. [Perform a production migration of a Bamboo pipeline](4-migrate.md) +2. [Perform an audit on Bamboo](2-audit.md) +3. [Forecast potential build runner usage](3-forecast.md) +4. [Perform a dry-run migration of a Bamboo pipeline](4-dry-run.md) +5. [Use custom transformers to customize GitHub Actions Importer's behavior](5-custom-transformers.md) +6. [Perform a production migration of a Bamboo pipeline](6-migrate.md) + + ## Troubleshoot the GitHub Actions Importer CLI diff --git a/bitbucket/3-forecast.md b/bitbucket/3-forecast.md index 733d0fe..d021e0b 100644 --- a/bitbucket/3-forecast.md +++ b/bitbucket/3-forecast.md @@ -32,7 +32,7 @@ Answer the following questions before running the `forecast` command: ```console [2023-09-07 18:26:22] Logs: 'tmp/audit/log/valet-20230907-182622.log' [2023-09-07 18:26:22] Forecasting 'https://bitbucket.org/actions-importer' - [2023-09-07 18:26:22] Output file(s): + [2023-09-07 18:26:22] Output file(s): [2023-09-07 18:26:22] tmp/forecast/forecast_report.md ``` ## Review the forecast report @@ -75,7 +75,7 @@ Here are some key terms of items defined in the forecast report: - 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. - `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 by hosted and self-hosted runners. +Additionally, these metrics are defined by hosted and self-hosted runners. ## Forecasting multiple providers From 7ce343a68704d5eed523fe2b7999199e9b22054b Mon Sep 17 00:00:00 2001 From: Chase S Date: Wed, 20 Sep 2023 09:49:09 -0500 Subject: [PATCH 15/18] Apply suggestions from Chase's review --- bamboo/1-configure.md | 4 ++-- bamboo/2-audit.md | 5 +++-- bamboo/3-forecast.md | 2 +- bamboo/4-dry-run.md | 5 +++-- bamboo/5-custom-transformers.md | 4 ++-- bamboo/6-migrate.md | 6 ++++-- 6 files changed, 15 insertions(+), 11 deletions(-) diff --git a/bamboo/1-configure.md b/bamboo/1-configure.md index a389472..0175f1c 100644 --- a/bamboo/1-configure.md +++ b/bamboo/1-configure.md @@ -2,7 +2,7 @@ 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 Bamboo and GitHub. -You will need to complete all of the setup instructions [here](./readme.md#configure-your-codespace) prior to performing this lab. +You will need to complete all of the [setup instructions](./readme.md#configure-your-codespace) prior to performing this lab. ## Configuring credentials @@ -24,7 +24,7 @@ You will need to complete all of the setup instructions [here](./readme.md#confi - At the GitHub PAT prompt, enter the GitHub PAT generated in step 2 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 Bamboo token prompt, enter the access token from step 1 and press enter. - - At the Bamboo URL prompt, enter your Bamboo URL. + - At the Bamboo URL prompt, enter your Bamboo Base URL. ## Verify your environment diff --git a/bamboo/2-audit.md b/bamboo/2-audit.md index e3d3f79..557eb2a 100644 --- a/bamboo/2-audit.md +++ b/bamboo/2-audit.md @@ -18,10 +18,11 @@ The `audit` command will perform the following steps: You will audit the configured Bamboo pipelines. Answer the following questions before running this command: 1. Where is the local configuration file? - - __bamboo/bootstrap/config.yml__ + - __bamboo/bootstrap/config.yml__ 2. Where do you want to store the result? - - __tmp/audit__. This can be any path within the working directory from which GitHub Actions Importer commands are executed. + - __tmp/audit__ + - This can be any path within the working directory from which GitHub Actions Importer commands are executed. ### Steps diff --git a/bamboo/3-forecast.md b/bamboo/3-forecast.md index bbcf2f6..c823952 100644 --- a/bamboo/3-forecast.md +++ b/bamboo/3-forecast.md @@ -4,7 +4,7 @@ In this lab you will use the `forecast` command to forecast potential GitHub Act ## Prerequisites -1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment. +1. Followed the [steps to set up your GitHub Codespaces](./readme.md#configure-your-codespace) environment. 2. Completed the [configure lab](./1-configure.md#configuring-credentials). ## Perform a forecast diff --git a/bamboo/4-dry-run.md b/bamboo/4-dry-run.md index aa6e89c..0952333 100644 --- a/bamboo/4-dry-run.md +++ b/bamboo/4-dry-run.md @@ -4,7 +4,7 @@ In this lab you will use the `dry-run` command to convert a Bamboo build plan to ## Prerequisites -1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment. +1. Followed the [steps to set up your GitHub Codespaces](./readme.md#configure-your-codespace) environment. 2. Completed the [configure lab](./1-configure.md#configuring-credentials). 3. Completed the [audit lab](./2-audit.md). @@ -17,7 +17,8 @@ You will be performing a dry run against a single Bamboo pipeline. Answer the fo - __MARS-ROCKET__ 2. Where do you want to store the result? - - __tmp/dry-run__. This can be any path within the working directory from which GitHub Actions Importer commands are executed. + - __tmp/dry-run__ + - This can be any path within the working directory from which GitHub Actions Importer commands are executed. 3. Which file would you like to convert? diff --git a/bamboo/5-custom-transformers.md b/bamboo/5-custom-transformers.md index abbbd0f..256b864 100644 --- a/bamboo/5-custom-transformers.md +++ b/bamboo/5-custom-transformers.md @@ -9,7 +9,7 @@ In this lab, you will build upon the `dry-run` command to override GitHub Action ## Prerequisites -1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment. +1. Followed the [steps to set up your GitHub Codespaces](./readme.md#configure-your-codespace) environment. 2. Completed the [configure lab](./1-configure.md#configuring-credentials). 3. Completed the [dry-run lab](./4-dry-run.md). @@ -177,7 +177,7 @@ end -That's it. Congratulations, you have overridden GitHub Actions Importer's default behavior by customizing the conversion of: +Congratulations! You have overridden GitHub Actions Importer's default behavior by customizing the conversion of: - Unknown steps - Runners diff --git a/bamboo/6-migrate.md b/bamboo/6-migrate.md index a4d2883..b36f044 100644 --- a/bamboo/6-migrate.md +++ b/bamboo/6-migrate.md @@ -4,7 +4,7 @@ In this lab, you will use the `migrate` command to convert a Bamboo plan and ope ## Prerequisites -1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment. +1. Followed the [steps to set up your GitHub Codespaces](./readme.md#configure-your-codespace) environment. 2. Completed the [configure lab](./1-configure.md#configuring-credentials). 3. Completed the [dry-run lab](./3-dry-run.md). @@ -17,7 +17,9 @@ Answer the following questions before running a `migrate` command: - __tmp/migrate__ 2. 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. + - __this repository__ + - The URL should follow the pattern with `:owner` and `:repo` replaced with your values. + 3. What is the source From e058da6a01b30c8a4b680a86fd3b65b4842d79ee Mon Sep 17 00:00:00 2001 From: Chase S Date: Wed, 20 Sep 2023 09:49:49 -0500 Subject: [PATCH 16/18] Apply suggestions from Joel's review Co-authored-by: j-dunham --- bamboo/1-configure.md | 6 ++++-- bamboo/5-custom-transformers.md | 8 ++++---- bamboo/6-migrate.md | 4 ++-- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/bamboo/1-configure.md b/bamboo/1-configure.md index 0175f1c..774a75a 100644 --- a/bamboo/1-configure.md +++ b/bamboo/1-configure.md @@ -17,13 +17,15 @@ You will need to complete all of the [setup instructions](./readme.md#configure- - Click `Generate token`. - Copy the generated PAT and save it in a safe location. +2. Create a Bamboo personal access token using the Bamboo [documentation](https://confluence.atlassian.com/bamboo/personal-access-tokens-976779873.html). This step is optional since we are using local files throughout the labs and a random value can be used instead. + 2. Run the `configure` CLI command: - Select the `TERMINAL` tab from within the codespace terminal. - Run the following command: `gh actions-importer configure`. - Use the down arrow key to highlight `Bamboo`, press the spacebar to select, and then press enter to continue. - - At the GitHub PAT prompt, enter the GitHub PAT generated in step 2 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 Bamboo token prompt, enter the access token from step 1 and press enter. + - At the Bamboo token prompt, enter the access token from step 2 and press enter. - At the Bamboo URL prompt, enter your Bamboo Base URL. ## Verify your environment diff --git a/bamboo/5-custom-transformers.md b/bamboo/5-custom-transformers.md index 256b864..d944a97 100644 --- a/bamboo/5-custom-transformers.md +++ b/bamboo/5-custom-transformers.md @@ -76,7 +76,7 @@ Let's answer the following questions before proceeding to write a custom transfo - Upon conducting some research, you've discovered that the [Actions Cache](https://github.com/marketplace/actions/cache) action in the marketplace offer comparable functionality. ```yaml - - uses: actions/cache/save@v3 + - uses: actions/cache@v3 with: path: key: @@ -94,7 +94,7 @@ Let's answer the following questions before proceeding to write a custom transfo transform "any-task/plugin-key/com.atlassian.bamboo.plugins.builder.unknowncache" do |item| [ { - "uses" => "azure/cache/save@v3", + "uses" => "actions/cache@v3", "with" => { "path" => item["configuration"]["path"], "key" => item["configuration"]["key"] @@ -139,7 +139,7 @@ With these questions answered, you can add the following code to the `transforme runner "bamboo-runner", "some-other-runner" ``` -In this example, the first parameter to the `runner` method is the runner label in Bitbucket and the second is the new runner label to use in GitHub Actions. +In this example, the first parameter to the `runner` method is the runner label in Bamboo and the second is the new runner label to use in GitHub Actions. Now you can perform another `dry-run` command with the `--custom-transformers` CLI option. When you open the converted workflow the `runs-on` statement will use the customized runner label: @@ -165,7 +165,7 @@ runner "bamboo-runner", "some-other-runner" transform "any-task/plugin-key/com.atlassian.bamboo.plugins.builder.unknowncache" do |item| [ { - "uses" => "azure/cache/save@v3", + "uses" => "actions/cache@v3", "with" => { "path" => item["configuration"]["path"], "key" => item["configuration"]["key"] diff --git a/bamboo/6-migrate.md b/bamboo/6-migrate.md index b36f044..b2096b6 100644 --- a/bamboo/6-migrate.md +++ b/bamboo/6-migrate.md @@ -7,7 +7,7 @@ In this lab, you will use the `migrate` command to convert a Bamboo plan and ope 1. Followed the [steps to set up your GitHub Codespaces](./readme.md#configure-your-codespace) environment. 2. Completed the [configure lab](./1-configure.md#configuring-credentials). -3. Completed the [dry-run lab](./3-dry-run.md). +3. Completed the [dry-run lab](./4-dry-run.md). ## Performing a migration @@ -28,7 +28,7 @@ Answer the following questions before running a `migrate` command: 1. Run the following `migrate` command in your codespace terminal: ```bash - $ gh actions-importer migrate bamboo build --target-url --output-dir tmp/migrate --source-file-path bamboo/bootstrap/source_files/bamboo/bamboo.yml + gh actions-importer migrate bamboo build -p MARS-ROCKET --target-url --output-dir tmp/migrate --source-file-path bamboo/bootstrap/source_files/bamboo/bamboo.yml ``` Note: The `--source-file-path` option is not required and is used throughout this lab to convert files that are stored locally. This can be omitted and GitHub Actions Importer will programmatically fetch pipeline definitions using the Bamboo REST APIs. From 8675b7f2c8e3b9ef13f72e1dc71fec912d38549b Mon Sep 17 00:00:00 2001 From: j-dunham Date: Wed, 20 Sep 2023 10:52:25 -0400 Subject: [PATCH 17/18] Update bamboo/1-configure.md --- bamboo/1-configure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bamboo/1-configure.md b/bamboo/1-configure.md index 774a75a..4af5259 100644 --- a/bamboo/1-configure.md +++ b/bamboo/1-configure.md @@ -19,7 +19,7 @@ You will need to complete all of the [setup instructions](./readme.md#configure- 2. Create a Bamboo personal access token using the Bamboo [documentation](https://confluence.atlassian.com/bamboo/personal-access-tokens-976779873.html). This step is optional since we are using local files throughout the labs and a random value can be used instead. -2. Run the `configure` CLI command: +3. Run the `configure` CLI command: - Select the `TERMINAL` tab from within the codespace terminal. - Run the following command: `gh actions-importer configure`. - Use the down arrow key to highlight `Bamboo`, press the spacebar to select, and then press enter to continue. From 811c306549746f9aea3eddd0f147cf6862d51ec2 Mon Sep 17 00:00:00 2001 From: j-dunham Date: Wed, 20 Sep 2023 10:55:05 -0400 Subject: [PATCH 18/18] Update bamboo/6-migrate.md --- bamboo/6-migrate.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/bamboo/6-migrate.md b/bamboo/6-migrate.md index b2096b6..f8a8050 100644 --- a/bamboo/6-migrate.md +++ b/bamboo/6-migrate.md @@ -13,15 +13,20 @@ In this lab, you will use the `migrate` command to convert a Bamboo plan and ope Answer the following questions before running a `migrate` command: -1. Where do you want to store the logs? +1. What is the plan slug of the pipeline you want to migrate? + - __MARS-ROCKET__ + +2. Where do you want to store the logs? - __tmp/migrate__ + +3. Which file would you like to convert? + - __bamboo/bootstrap/source_files/bamboo/bamboo.yml__ -2. 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. +4. Are you converting a build or deployment plan? + - The supplied configuration is a build plan. - -3. What is the source +5. 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