From f7573c22ad82a6dc705ed42ae9623c222ef09d09 Mon Sep 17 00:00:00 2001 From: Ethan Dennis Date: Wed, 31 Aug 2022 21:00:10 -0700 Subject: [PATCH] Copy edit jenkins readme --- jenkins/readme.md | 128 +++++++++++++++++++++++++--------------------- 1 file changed, 70 insertions(+), 58 deletions(-) diff --git a/jenkins/readme.md b/jenkins/readme.md index 6ac095f..d2c05cb 100644 --- a/jenkins/readme.md +++ b/jenkins/readme.md @@ -1,88 +1,100 @@ -# Valet labs for Jenkins +# Migrating from Jenkins to Actions with Valet -This lab bootstraps a Valet environment using GitHub Codespaces and enables you to spin up a Jenkins instance against which to run the Valet CI/CD migration tool. +The instructions below will guide you through configuring a GitHub Codespace environment that will be used in subsequent labs that demonstrate how to use Valet to migrate Jenkins pipelines to GitHub Actions. -- [Use this repo as a template](#repo-template) -- [Use Valet with a codespace](#use-valet-with-a-codespace) -- [Bootstrap Jenkins](#bootstrap-jenkins) -- [Labs for Jenkins](#labs-for-jenkins) -- [Troubleshoot GH Valet extension](#troubleshoot-gh-valet-extension) -- [Troubleshooting Jenkins](#troubleshooting-jenkins) +These steps **must** be completed prior to starting other labs. -## Repo template +## Create your own repository for these labs -1. Verify you are in your own Repository created from the landing page [Valet Labs](https://github.com/valet-customers/labs). +1. Ensure that you have created a repository using the [valet-customers/labs](https://github.com/valet-customers/labs) as a template. -## Use Valet with a codespace +## Configure your Codespace -1. Start the codespace - - Click the `Code` with button down arrow above repository on the repository's landing page. - - Click the `Codespaces` tab - - Click `Create codespaces on main` to create the codespace. If you are in another branch then the `main` branch, the codespace will button will have the current branch specified. - - Wait a couple minutes, then verify that the codespace starts up. Once it is fully booted up, the terminal should be present. -2. Verify Valet CLI is installed and working. More information on the [GitHub Valet CLI extension](https://github.com/github/gh-valet) - - Verify Valet CLI is installed and working - - Run the following command in the Visual Studio Code terminal: +1. Start a new Codespace. - ``` - gh valet version - ``` +- Click the `Code` with button down arrow above repository on the 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. - - Verify the output looks like the below image. Note the valet version will be different than below as the latest version gets pulled down. - - If `gh valet version` did not produce a similar image with a version please follow these instructions [Troubleshoot GH Valet extension](#troubleshoot-gh-valet-extension) +2. Verify the Valet CLI is installed and working. More information on the Valet extension for the official GitHub CLI can be found [here](https://github.com/github/gh-valet). -Screen Shot 2022-08-10 at 1 45 20 PM +- Run the following command in the codespace's terminal: -## Bootstrap Jenkins + ```bash + gh valet version + ``` - 1. Run the Jenkins setup script. This script will setup Jenkins and ensure it is ready to use. In general, this script should be run first if you are starting a new codespace or restarting an existing one. +- Verify the output is similar to the image below. The version information may differ than what is shown below. + - If `gh valet version` did not produce similar output then please follow the troubleshooting [guide](#troubleshoot-the-valet-cli). -- Navigate to the terminal within your Codespace. -- Run the following command to kick off the creation of your Jenkins instance: + ![img](https://user-images.githubusercontent.com/19557880/186771327-631e8839-3614-4ab7-8108-818b5a0c6e93.png) - ``` +## Bootstrap a Jenkins server + + 1. Execute the Jenkins setup script that will start a container with a Jenkins server running inside of it. This script should be executed when starting a new Codespace or restarting an existing one. + +- Run the following command from the codespace's terminal to start a Jenkins server: + + ```bash ./jenkins/bootstrap/setup.sh ``` -- After a couple seconds, a pop-up box should appear with a link to the forwarded URL for your Jenkins instance. -- You can also access the forwarded URL by going to the `Ports` tab in your terminal. Right click on the URL listed under the `Local Address` and clicking the `Open in Browser` tab. -- Once you have navigated to the url, the following default credentials have been assigned: +- After some time, a pop-up box should appear with a link to the URL for your Jenkins server. + - You can also access the URL by going to the `Ports` tab in your terminal. Right click on the URL listed under the `Local Address` and click the `Open in Browser` tab. - - username: `admin` - - password: `password` +2. Open the Jenkins server in your browser and use the following credentials to authenticate: -2. Click the `Sign in` button and you should now see your new Jenkins instance with a few pre-populated pipelines. + - Username: `admin` + - Password: `password` + +- Once authenticated, you should see a Jenkins server with a few predefined pipelines. ## Labs for Jenkins Perform the following labs to test-drive Valet -- [Configure Valet to work with Jenkins](valet-configure-lab.md#configure-valet-to-work-with-jenkins) -- [Audit Jenkins using the Valet audit command](valet-audit-lab.md#audit-jenkins-pipelines-using-the-valet-audit-command) -- [Dry-run the migration of an Jenkins pipeline to GitHub Actions](valet-dry-run-lab.md#dry-run-the-migration-of-a-jenkins-pipeline-to-github-actions) -- [Using Custom Transformers in a dry-run](valet-custom-transformers-lab.md#using-custom-transformers-in-a-dry-run) -- [Migrate an Jenkins Project to GitHub Actions](valet-migrate-lab.md#migrate-a-jenkins-project-to-github-actions) -- [Forecast the usage of a Jenkins namespace](valet-forecast-lab.md#forecast-the-runner-usage-of-a-jenkins-instance) +- [Configure credentials for Valet](1-configure.md) +- [Perform an audit of a Jenkins server](2-audit.md) +- [Perform a dry-run of a Jenkins pipeline](3-dry-run.md) +- [Use custom transformers to customize Valet's behavior](4-custom-transformers.md) +- [Perform a production migration of a Jenkins pipeline](5-migrate.md) +- [Forecast potential build runner usage](6-forecast.md) -## Troubleshoot GH Valet extension +## Troubleshoot the Valet CLI -Manually Install the GitHub CLI Valet extension. More information on the [GitHub Valet CLI extension](https://github.com/github/gh-valet) +The CLI extension for Valet can be manually installed by following these steps: - Verify you are in the codespace terminal -- Run this command to install the GitHub Valet extension -- `gh extension install github/gh-valet` -- Verify the result of the install is: `✓ Installed extension github/gh-valet` -- If you get a similar error to the following, click the link to authorize the token - - Restart Codespace after clicking the link -- Verify Valet CLI is installed and working by running `gh valet version` +- Run this command from within the codespace's terminal: - ![linktolcickauth](https://user-images.githubusercontent.com/26442605/169588015-9414404f-82b6-4d0f-89d4-5f0e6941b029.png) - -## Troubleshooting Jenkins + ```bash + gh extension install github/gh-valet + ``` -1. Navigate to the Docker tab on your left hand side. -2. Under the `Containers` tab you should see a Docker container `jenkins:valet` listed with a green play button ▶ - - If you see the `jenkins:valet` container, but it has a red stopped symbol next to it ▢, right click on the container and click on `start`, the container should begin running again. - - If the container does not start even after trying to manually start it, right click on the `jenkins:valet` container and click the `remove` button. Next continue by following all the #bootstrap-jenkins instructions again. +- Verify the result of the install contains: - Screen Shot 2022-08-09 at 3 06 46 PM + ```bash + ✓ Installed extension github/gh-valet + ``` + +- If you get an error similar to the image below, then click the link in the terminal output to authorize the token. + - Restart the codespace after clicking the link. + ![img](https://user-images.githubusercontent.com/26442605/169588015-9414404f-82b6-4d0f-89d4-5f0e6941b029.png) +- Verify Valet CLI extension is installed and working by running the following command from the codespace's terminal: + + ```bash + gh valet version + ``` + +## Troubleshooting the Jenkins server + +Follow these steps if the Jenkins server does not start correctly after running the setup script: + +1. Navigate to the `Docker` tab on the left side of the codespace. +2. Under the `Containers` tab you should see a docker container named `jenkins:valet` listed with a green play button ▶ + +- If you see the `jenkins:valet` container, but it has a red stopped symbol next to it ▢, right click on the container and click on `start`, the container should begin running again. +- If the container does not start even after trying to manually start it, right click on the `jenkins:valet` container and click the `remove` button. Then, attempt to start the Jenkins server again by following the steps [here](#bootstrap-a-jenkins-server). + +![img](https://user-images.githubusercontent.com/19557880/183770210-c0386616-656e-4fe9-9324-b410ad62c406.png)