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] 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)