diff --git a/.gitignore b/.gitignore index c05f815..46e2c04 100644 --- a/.gitignore +++ b/.gitignore @@ -1,356 +1,3 @@ -## Ignore Visual Studio temporary files, build results, and -## files generated by popular Visual Studio add-ons. -## -## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore - -# User-specific files -*.rsuser -*.suo -*.user -*.userosscache -*.sln.docstates - -# User-specific files (MonoDevelop/Xamarin Studio) -*.userprefs - -# Mono auto generated files -mono_crash.* - -# Build results -[Dd]ebug/ -[Dd]ebugPublic/ -[Rr]elease/ -[Rr]eleases/ -x64/ -x86/ -[Aa][Rr][Mm]/ -[Aa][Rr][Mm]64/ -bld/ -[Bb]in/ -[Oo]bj/ -[Ll]og/ -[Ll]ogs/ - -# Visual Studio 2015/2017 cache/options directory -.vs/ -# Uncomment if you have tasks that create the project's static files in wwwroot -#wwwroot/ - -# Visual Studio 2017 auto generated files -Generated\ Files/ - -# MSTest test Results -[Tt]est[Rr]esult*/ -[Bb]uild[Ll]og.* - -# NUnit -*.VisualState.xml -TestResult.xml -nunit-*.xml - -# Build Results of an ATL Project -[Dd]ebugPS/ -[Rr]eleasePS/ -dlldata.c - -# Benchmark Results -BenchmarkDotNet.Artifacts/ - -# .NET Core -project.lock.json -project.fragment.lock.json -artifacts/ - -# StyleCop -StyleCopReport.xml - -# Files built by Visual Studio -*_i.c -*_p.c -*_h.h -*.ilk -*.meta -*.obj -*.iobj -*.pch -*.pdb -*.ipdb -*.pgc -*.pgd -*.rsp -*.sbr -*.tlb -*.tli -*.tlh -*.tmp -*.tmp_proj -*_wpftmp.csproj -*.log -*.vspscc -*.vssscc -.builds -*.pidb -*.svclog -*.scc - -# Chutzpah Test files -_Chutzpah* - -# Visual C++ cache files -ipch/ -*.aps -*.ncb -*.opendb -*.opensdf -*.sdf -*.cachefile -*.VC.db -*.VC.VC.opendb - -# Visual Studio profiler -*.psess -*.vsp -*.vspx -*.sap - -# Visual Studio Trace Files -*.e2e - -# TFS 2012 Local Workspace -$tf/ - -# Guidance Automation Toolkit -*.gpState - -# ReSharper is a .NET coding add-in -_ReSharper*/ -*.[Rr]e[Ss]harper -*.DotSettings.user - -# TeamCity is a build add-in -_TeamCity* - -# DotCover is a Code Coverage Tool -*.dotCover - -# AxoCover is a Code Coverage Tool -.axoCover/* -!.axoCover/settings.json - -# Visual Studio code coverage results -*.coverage -*.coveragexml - -# NCrunch -_NCrunch_* -.*crunch*.local.xml -nCrunchTemp_* - -# MightyMoose -*.mm.* -AutoTest.Net/ - -# Web workbench (sass) -.sass-cache/ - -# Installshield output folder -[Ee]xpress/ - -# DocProject is a documentation generator add-in -DocProject/buildhelp/ -DocProject/Help/*.HxT -DocProject/Help/*.HxC -DocProject/Help/*.hhc -DocProject/Help/*.hhk -DocProject/Help/*.hhp -DocProject/Help/Html2 -DocProject/Help/html - -# Click-Once directory -publish/ - -# Publish Web Output -*.[Pp]ublish.xml -*.azurePubxml -# Note: Comment the next line if you want to checkin your web deploy settings, -# but database connection strings (with potential passwords) will be unencrypted -*.pubxml -*.publishproj - -# Microsoft Azure Web App publish settings. Comment the next line if you want to -# checkin your Azure Web App publish settings, but sensitive information contained -# in these scripts will be unencrypted -PublishScripts/ - -# NuGet Packages -*.nupkg -# NuGet Symbol Packages -*.snupkg -# The packages folder can be ignored because of Package Restore -**/[Pp]ackages/* -# except build/, which is used as an MSBuild target. -!**/[Pp]ackages/build/ -# Uncomment if necessary however generally it will be regenerated when needed -#!**/[Pp]ackages/repositories.config -# NuGet v3's project.json files produces more ignorable files -*.nuget.props -*.nuget.targets - -# Microsoft Azure Build Output -csx/ -*.build.csdef - -# Microsoft Azure Emulator -ecf/ -rcf/ - -# Windows Store app package directories and files -AppPackages/ -BundleArtifacts/ -Package.StoreAssociation.xml -_pkginfo.txt -*.appx -*.appxbundle -*.appxupload - -# Visual Studio cache files -# files ending in .cache can be ignored -*.[Cc]ache -# but keep track of directories ending in .cache -!?*.[Cc]ache/ - -# Others -ClientBin/ -~$* -*~ -*.dbmdl -*.dbproj.schemaview -*.jfm -*.pfx -*.publishsettings -orleans.codegen.cs - -# Including strong name files can present a security risk -# (https://github.com/github/gitignore/pull/2483#issue-259490424) -#*.snk - -# Since there are multiple workflows, uncomment next line to ignore bower_components -# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622) -#bower_components/ - -# RIA/Silverlight projects -Generated_Code/ - -# Backup & report files from converting an old project file -# to a newer Visual Studio version. Backup files are not needed, -# because we have git ;-) -_UpgradeReport_Files/ -Backup*/ -UpgradeLog*.XML -UpgradeLog*.htm -ServiceFabricBackup/ -*.rptproj.bak - -# SQL Server files -*.mdf -*.ldf -*.ndf - -# Business Intelligence projects -*.rdl.data -*.bim.layout -*.bim_*.settings -*.rptproj.rsuser -*- [Bb]ackup.rdl -*- [Bb]ackup ([0-9]).rdl -*- [Bb]ackup ([0-9][0-9]).rdl - -# Microsoft Fakes -FakesAssemblies/ - -# GhostDoc plugin setting file -*.GhostDoc.xml - -# Node.js Tools for Visual Studio -.ntvs_analysis.dat -node_modules/ - -# Visual Studio 6 build log -*.plg - -# Visual Studio 6 workspace options file -*.opt - -# Visual Studio 6 auto-generated workspace file (contains which files were open etc.) -*.vbw - -# Visual Studio LightSwitch build output -**/*.HTMLClient/GeneratedArtifacts -**/*.DesktopClient/GeneratedArtifacts -**/*.DesktopClient/ModelManifest.xml -**/*.Server/GeneratedArtifacts -**/*.Server/ModelManifest.xml -_Pvt_Extensions - -# Paket dependency manager -.paket/paket.exe -paket-files/ - -# FAKE - F# Make -.fake/ - -# CodeRush personal settings -.cr/personal - -# Python Tools for Visual Studio (PTVS) -__pycache__/ -*.pyc - -# Cake - Uncomment if you are using it -# tools/** -# !tools/packages.config - -# Tabs Studio -*.tss - -# Telerik's JustMock configuration file -*.jmconfig - -# BizTalk build output -*.btp.cs -*.btm.cs -*.odx.cs -*.xsd.cs - -# OpenCover UI analysis results -OpenCover/ - -# Azure Stream Analytics local run output -ASALocalRun/ - -# MSBuild Binary and Structured Log -*.binlog - -# NVidia Nsight GPU debugger configuration file -*.nvuser - -# MFractors (Xamarin productivity tool) working folder -.mfractor/ - -# Local History for Visual Studio -.localhistory/ - -# BeatPulse healthcheck temp database -healthchecksdb - -# Backup folder for Package Reference Convert tool in Visual Studio 2017 -MigrationBackup/ - -# Ionide (cross platform F# VS Code tools) working folder -.ionide/ - -# valet files -.env*local -credentials_file.yaml - -.vscode \ No newline at end of file +.env.local +.cache/ +tmp/ diff --git a/jenkins/1-configure.md b/jenkins/1-configure.md index 0e1fabe..8128140 100644 --- a/jenkins/1-configure.md +++ b/jenkins/1-configure.md @@ -54,7 +54,8 @@ To verify your environment is configured correctly, run the `update` CLI command 2. You should see a confirmation that you were logged into the GitHub Container Registry and Valet was updated to the latest version. - ```bash + ```console + $ gh valet update Login Succeeded latest: Pulling from valet-customers/valet-cli Digest: sha256:a7d00dee8a37e25da59daeed44b1543f476b00fa2c41c47f48deeaf34a215bbb diff --git a/jenkins/2-audit.md b/jenkins/2-audit.md index e2c8b35..1fcc5cc 100644 --- a/jenkins/2-audit.md +++ b/jenkins/2-audit.md @@ -17,7 +17,7 @@ You will be performing an audit against your preconfigured Jenkins server. Answe - In this example you will audit the entire Jenkins instance, but in the future if you wanted to configure a specific folder to be audited add the `-f ` flag to the `audit` command. 2. Where do you want to store the result? - - __./tmp/audit__. This can be any path within the working directory from which Valet commands are executed. + - __tmp/audit__. This can be any path within the working directory from which Valet commands are executed. ### Steps @@ -30,7 +30,30 @@ You will be performing an audit against your preconfigured Jenkins server. Answe 3. The command will list all the files written to disk in green when the command succeeds. - ![img](https://user-images.githubusercontent.com/19557880/184682347-b19760fa-36a6-423e-a445-bb30eda5ac59.png) + ```console + $ gh valet audit jenkins --output-dir tmp/audit + [2022-08-20 22:08:20] Logs: 'tmp/audit/log/valet-20220916-015817.log' + [2022-08-20 22:08:20] Auditing 'http://localhost:8080/' + [2022-08-20 22:08:20] Output file(s):==========================================| + [2022-08-20 22:08:20] tmp/audit/demo_pipeline.yml + [2022-08-20 22:08:20] tmp/audit/demo_pipeline.config.json + [2022-08-20 22:08:20] tmp/audit/demo_pipeline.jenkinsfile + [2022-08-20 22:08:20] tmp/audit/groovy_script.error.txt + [2022-08-20 22:08:20] tmp/audit/groovy_script.config.json + [2022-08-20 22:08:20] tmp/audit/monas_dev_work/monas_freestyle.yml + [2022-08-20 22:08:20] tmp/audit/monas_dev_work/monas_freestyle.config.json + [2022-08-20 22:08:20] tmp/audit/monas_dev_work/monas_pipeline.yml + [2022-08-20 22:08:20] tmp/audit/monas_dev_work/monas_pipeline.config.json + [2022-08-20 22:08:20] tmp/audit/monas_dev_work/monas_pipeline.jenkinsfile + [2022-08-20 22:08:20] tmp/audit/test_freestyle_project.yml + [2022-08-20 22:08:20] tmp/audit/test_freestyle_project.config.json + [2022-08-20 22:08:20] tmp/audit/test_mutlibranch_pipeline.config.json + [2022-08-20 22:08:20] tmp/audit/test_pipeline.yml + [2022-08-20 22:08:20] tmp/audit/test_pipeline.config.json + [2022-08-20 22:08:20] tmp/audit/test_pipeline.jenkinsfile + [2022-08-20 22:08:20] tmp/audit/workflow_usage.csv + [2022-08-20 22:08:20] tmp/audit/audit_summary.md + ``` ## Inspect the output files @@ -46,7 +69,24 @@ The audit summary, logs, config files, jenkinsfiles, and transformed workflows w The pipeline summary section contains high level statistics regarding the conversion rate done by Valet: - ![img](https://user-images.githubusercontent.com/19557880/184683664-81985baf-5c03-4765-a067-f4023416e3ea.png) +> Total: __7__ +> +> - Successful: __3 (42%)__ +> - Partially successful: __3 (42%)__ +> - Unsupported: __1 (14%)__ +> - Failed: __0 (0%)__ +> +> ### Job types +> +> Supported: __6 (85%)__ +> +> - flow-definition: __3__ +> - project: __2__ +> - org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProject: __1__ +> +> Unsupported: __1 (14%)__ +> +> - scripted: __1__ Here are some key terms in the “Pipelines” section in the above example: @@ -67,7 +107,31 @@ The "Job types" section will summarize which types of pipelines are being used a The build steps summary section presents an overview of the individual build steps that are used across all pipelines and how many were automatically converted by Valet. - ![img](https://user-images.githubusercontent.com/19557880/184684062-69ab0bde-5e32-45f8-a7dd-ed4655872975.png) +> Total: __17__ +> +> Known: __13 (76%)__ +> +> - echo: __6__ +> - hudson.tasks.Shell: __3__ +> - junit: __2__ +> - archiveArtifacts: __1__ +> - sh: __1__ +> +> Unknown: __3 (17%)__ +> +> - sleep: __2__ +> - hudson.plugins.git.GitPublisher: __1__ +> +> Unsupported: __1 (5%)__ +> +> - hudson.tasks.Mailer: __1__ +> +> Actions: __22__ +> +> - run: __10__ +> - actions/checkout@v2: __9__ +> - EnricoMi/publish-unit-test-result-action@v1.7: __2__ +> - actions/upload-artifact@v2: __1__ Here are some key terms in the "Build steps" section in the above example: @@ -86,7 +150,17 @@ 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 Valet is not able to complete automatically. - ![img](https://user-images.githubusercontent.com/19557880/184684249-9accfd94-c2df-4891-af56-dcff66beb557.png) +> Total: __9__ +> +> Secrets: __2__ +> +> - `${{ secrets.SECRET_TEST_EXPRESSION_VAR }}`: __1__ +> - `${{ secrets.EXPRESSION_FIRST_VAR }}`: __1__ +> +> Self hosted runners: __7__ +> +> - `TeamARunner`: __6__ +> - `DemoRunner`: __1__ Here are some key terms in the “Manual tasks” section in the above example: @@ -97,7 +171,48 @@ Here are some key terms in the “Manual tasks” section in the above example: The final section of the audit report provides a manifest of all of the files that are written to disk during the audit. These files include: - ![img](https://user-images.githubusercontent.com/19557880/184684416-b3db774e-4ab8-46e0-91ad-e503632df5cb.png) +> ### Successful +> +> #### demo_pipeline +> +> - [demo_pipeline.yml](demo_pipeline.yml) +> - [demo_pipeline.config.json](demo_pipeline.config.json) +> - [demo_pipeline.jenkinsfile](demo_pipeline.jenkinsfile) +> +> #### monas_dev_work/monas_freestyle +> +> - [monas_dev_work/monas_freestyle.yml](monas_dev_work/monas_freestyle.yml) +> - [monas_dev_work/monas_freestyle.config.json](monas_dev_work/monas_freestyle.config.json) +> +> #### test_mutlibranch_pipeline +> +> - [test_mutlibranch_pipeline.config.json](test_mutlibranch_pipeline.config.json) +> +> ### Partially successful +> +> #### monas_dev_work/monas_pipeline +> +> - [monas_dev_work/monas_pipeline.yml](monas_dev_work/monas_pipeline.yml) +> - [monas_dev_work/monas_pipeline.config.json](monas_dev_work/monas_pipeline.config.json) +> - [monas_dev_work/monas_pipeline.jenkinsfile](monas_dev_work/monas_pipeline.jenkinsfile) +> +> #### test_freestyle_project +> +> - [test_freestyle_project.yml](test_freestyle_project.yml) +> - [test_freestyle_project.config.json](test_freestyle_project.config.json) +> +> #### test_pipeline +> +> - [test_pipeline.yml](test_pipeline.yml) +> - [test_pipeline.config.json](test_pipeline.config.json) +> - [test_pipeline.jenkinsfile](test_pipeline.jenkinsfile) +> +> ### Failed +> +> #### groovy_script +> +> - [groovy_script.error.txt](groovy_script.error.txt) +> - [groovy_script.config.json](groovy_script.config.json) Each pipeline will have a variety of files written that include: diff --git a/jenkins/3-forecast.md b/jenkins/3-forecast.md index 7748a1f..7344c0a 100644 --- a/jenkins/3-forecast.md +++ b/jenkins/3-forecast.md @@ -5,7 +5,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 and start a Jenkins server. -2. Completed the [configure lab](./1-configure-lab.md#configuring-credentials). +2. Completed the [configure lab](./1-configure.md#configuring-credentials). ## Perform a forecast @@ -18,7 +18,7 @@ Answer the following questions before running the `forecast` command: - __2022-08-02__. This date is needed as it is prior to when the data was seeded in Jenkins for these labs. This value defaults to the date one week ago, however, you should use a start date that will show a representative view of typical usage. 3. Where do you want to store the results? - - `./tmp/forecast_reports` + - `tmp/forecast` ### Steps @@ -26,16 +26,23 @@ Answer the following questions before running the `forecast` command: 2. Run the following command from the root directory: ```bash - gh valet forecast jenkins --output-dir ./tmp/forecast_reports --start-date 2022-08-02 + gh valet forecast jenkins --output-dir tmp/forecast --start-date 2022-08-02 ``` 3. The command will list all the files written to disk when the command succeeds. - ![img](https://user-images.githubusercontent.com/19557880/186223037-18556c82-5a29-4434-bc17-4b906d704967.png) + ```console + $ gh valet forecast jenkins --output-dir tmp/forecast --start-date 2022-08-02 + [2022-08-20 22:08:20] Logs: 'tmp/forecast/log/valet-20220916-021004.log' + [2022-08-20 22:08:20] Forecasting 'http://localhost:8080/' + [2022-08-20 22:08:20] Output file(s): + [2022-08-20 22:08:20] tmp/forecast/jobs/09-16-2022-02-10_jobs_0.json + [2022-08-20 22:08:20] tmp/forecast/forecast_report.md + ``` ## Review the forecast report -The forecast report, logs, and completed job data will be located within the `tmp/forecast_reports` folder. +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`. @@ -45,32 +52,30 @@ The forecast report, logs, and completed job data will be located within the `tm 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: __73__ -- Pipeline count: __6__ - -- Execution time - - - Total: __27,057 minutes__ - - Median: __2 minutes__ - - P90: __19 minutes__ - - Min: __0 minutes__ - - Max: __15,625 minutes__ - -- Queue time - - - Median: __0 minutes__ - - P90: __0 minutes__ - - Min: __0 minutes__ - - Max: __0 minutes__ - -- Concurrent jobs - - - Median: __1__ - - P90: __3__ - - Min: __0__ - - Max: __29__ -``` +> - Job count: __73__ +> - Pipeline count: __6__ +> +> - Execution time +> +> - Total: __27,057 minutes__ +> - Median: __2 minutes__ +> - P90: __19 minutes__ +> - Min: __0 minutes__ +> - Max: __15,625 minutes__ +> +> - Queue time +> +> - Median: __0 minutes__ +> - P90: __0 minutes__ +> - Min: __0 minutes__ +> - Max: __0 minutes__ +> +> - Concurrent jobs +> +> - Median: __1__ +> - P90: __3__ +> - Min: __0__ +> - Max: __29__ Here are some key terms of items defined in the forecast report: @@ -85,16 +90,32 @@ Additionally, these metrics are defined for each queue of runners defined in Jen ## Forecasting multiple providers -You can examine the available options for the `forecast` command by running `gh valet forecast --help`. When you do this you will see the `--source-file-path` option: +You can examine the available options for the `forecast` command by running `gh valet forecast jenkins --help`. When you do this you will see the `--source-file-path` option: -![img](https://user-images.githubusercontent.com/19557880/186263140-f02c6cab-7979-417c-bdfe-b9590e9c5597.png) +```console +$ gh valet forecast jenkins --help +Options: + -u, --jenkins-instance-url The URL of the Jenkins CI instance. + -n, --jenkins-username Username for the Jenkins instance. + -t, --jenkins-access-token Access token for the Jenkins instance. + -f, --folders Folders to forecast in the instance + --source-file-path 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/9/2022 2:14:15 AM] + --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 wanted to get a holistic view of the runner usage. This works by using the `.json` files generated by `forecast` commands as space-delimited values for the `--source-file-path` CLI option. Optionally, this value could be a glob pattern to dynamically specify the list of files (e.g. `**/*.json`). Run the following command from within the codespace terminal: ```bash -gh valet forecast --source-file-path tmp/**/jobs/*.json --output-dir tmp/combined-forecast +gh valet forecast --source-file-path tmp/**/jobs/*.json --output-dir tmp/forecast-combined ``` You can now inspect the output of the command to see a forecast report using all of the files matching the `tmp/**/jobs/*.json` pattern. diff --git a/jenkins/4-dry-run.md b/jenkins/4-dry-run.md index e0cd0d8..e24f7cd 100644 --- a/jenkins/4-dry-run.md +++ b/jenkins/4-dry-run.md @@ -5,7 +5,7 @@ In this lab you will use the `dry-run` command to convert a Jenkins pipeline to ## Prerequisites 1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment and start a Jenkins server. -2. Completed the [configure lab](./1-configure-lab.md#configuring-credentials). +2. Completed the [configure lab](./1-configure.md#configuring-credentials). 3. Completed the [audit lab](./2-audit.md). ## Perform a dry run @@ -19,7 +19,7 @@ You will be performing a dry run against a pipeline in your preconfigured Jenkin - ____ 3. Where do you want to store the result? - - __./tmp/dry-run-lab__. This can be any path within the working directory from which Valet commands are executed. + - __tmp/dry-run__. This can be any path within the working directory from which Valet commands are executed. ### Steps @@ -27,15 +27,20 @@ You will be performing a dry run against a pipeline in your preconfigured Jenkin 2. Run the following command from the root directory: ```bash - gh valet dry-run jenkins --source-url http://localhost:8080/job/test_pipeline --output-dir .tmp/jenkins/dry-run + gh valet dry-run jenkins --source-url http://localhost:8080/job/test_pipeline --output-dir tmp/dry-run ``` 3. The command will list all the files written to disk when the command succeeds. - ![img](https://user-images.githubusercontent.com/19557880/184935603-5c2d4dfe-66ef-4cb1-9398-e96954ca72e3.png) + ```console + $ gh valet dry-run jenkins --source-url http://localhost:8080/job/test_pipeline --output-dir tmp/dry-run + [2022-08-20 22:08:20] Logs: 'tmp/dry-run/log/valet-20220916-022338.log' + [2022-08-20 22:08:20] Output file(s): + [2022-08-20 22:08:20] tmp/dry-run/test_pipeline.yml + ``` 4. View the converted workflow: - - Find `./tmp/dry-run` in the file explorer pane in your codespace. + - Find `tmp/dry-run` in the file explorer pane in your codespace. - Click `test_pipeline.yml` to open ## Inspect the output files @@ -66,7 +71,7 @@ pipeline { } stage('test') { steps{ - junit '**/target/*.xml' + junit '**/target/*.xml' } } } diff --git a/jenkins/5-custom-transformers.md b/jenkins/5-custom-transformers.md index 129509f..91a9f6e 100644 --- a/jenkins/5-custom-transformers.md +++ b/jenkins/5-custom-transformers.md @@ -10,15 +10,15 @@ In this lab you will build upon the `dry-run` command to override Valet's defaul ## Prerequisites 1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment and start a Jenkins server. -2. Completed the [configure lab](./1-configure-lab.md#configuring-credentials). -3. Completed the [dry-run lab](./3-dry-run.md). +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 valet dry-run jenkins --source-url http://localhost:8080/job/test_pipeline --output-dir tmp/jenkins/dry-run +gh valet dry-run jenkins --source-url http://localhost:8080/job/test_pipeline --output-dir tmp/dry-run ``` The converted workflow that is generated by the above command can be seen below: @@ -71,7 +71,7 @@ jobs: -_Note_: You can refer to the previous [lab](./3-dry-run.md) to learn about the fundamentals of the `dry-run` command. +_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 @@ -114,7 +114,7 @@ This method can use any valid ruby syntax and should return a `Hash` that repres 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 valet dry-run jenkins --source-url http://localhost:8080/job/test_pipeline --output-dir tmp/jenkins/dry-run --custom-transformers transformers.rb +gh valet dry-run jenkins --source-url http://localhost:8080/job/test_pipeline --output-dir tmp/dry-run --custom-transformers transformers.rb ``` Open the workflow that is generated and inspect the contents. Now the `sleep` step is converted and uses the customized behavior! @@ -160,7 +160,13 @@ end Now, we can perform another `dry-run` command with the `--custom-transformers` CLI option. The output of the `dry-run` command should look similar to this: -![img](https://user-images.githubusercontent.com/19557880/186782050-65ece0c4-52a3-4f88-818f-0f860c50c2b7.png) +```console +$ gh valet dry-run jenkins --source-url http://localhost:8080/job/test_pipeline --output-dir tmp/dry-run --custom-transformers transformers.rb +[2022-08-20 22:08:20] Logs: 'tmp/dry-run/log/valet-20220916-022628.log' +This is the item: {"name"=>"junit", "arguments"=>[{"key"=>"testResults", "value"=>{"isLiteral"=>true, "value"=>"**/target/*.xml"}}]} +[2022-08-20 22:08:20] Output file(s): +[2022-08-20 22:08:20] tmp/dry-run/test_pipeline.yml +``` Now that you know the data structure of `item`, you can access the file path programmatically by editing the custom transformer to the following: @@ -207,7 +213,7 @@ env "DB_ENGINE", "mongodb" In this example, the first parameter to the `env` method is the environment variable name and the second is the updated value. -Now you can perform another `dry-run` command with the `--custom-transformers` CLI option. When you open the converted workflow the `DB_ENGINE` environment variable will be set to `mongodb`: +Now you can perform another `dry-run` command with the `--custom-transformers` CLI option. When you open the converted workflow the `DB_ENGINE` environment variable will be set to `mongodb`: ```diff env: @@ -234,7 +240,7 @@ runner "TeamARunner", "ubuntu-latest" In this example, the first parameter to the `runner` method is the Jenkins label and the second is the Actions runner label. -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: +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: ```diff runs-on: diff --git a/jenkins/6-migrate.md b/jenkins/6-migrate.md index 325a620..e922bec 100644 --- a/jenkins/6-migrate.md +++ b/jenkins/6-migrate.md @@ -5,9 +5,9 @@ In this lab, you will use the `migrate` command to convert a Jenkins pipeline an ## Prerequisites 1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment and start a Jenkins server. -2. Completed the [configure lab](./1-configure-lab.md#configuring-credentials). -3. Completed the [dry-run lab](./3-dry-run.md). -4. Completed the [custom transformers lab](./4-custom-transformers.md). +2. Completed the [configure lab](./1-configure.md#configuring-credentials). +3. Completed the [dry-run lab](./4-dry-run.md). +4. Completed the [custom transformers lab](./5-custom-transformers.md). ## Performing a migration @@ -16,7 +16,7 @@ Answer the following questions before running a `migrate` command: 1. What is the source URL of the pipeline you want to convert? - ____ 2. Where do you want to store the logs? - - __./tmp/migrate__ + - __tmp/migrate__ 3. What is the URL for the GitHub repository to add the workflow to? - __this repository__. The URL should follow the pattern with `:owner` and `:repo` replaced with your values. @@ -25,12 +25,16 @@ Answer the following questions before running a `migrate` command: 1. Run the following `migrate` command in your codespace terminal: ```bash - gh valet migrate jenkins --target-url https://github.com/:owner/:repo --output-dir ./tmp/migrate --source-url http://localhost:8080/job/monas_dev_work/job/monas_freestyle + gh valet migrate jenkins --target-url https://github.com/:owner/:repo --output-dir tmp/migrate --source-url http://localhost:8080/job/monas_dev_work/job/monas_freestyle ``` 2. The command will write the URL to the pull request that was created when the command succeeds. - ![img](https://user-images.githubusercontent.com/19557880/185509412-ab64d92d-2a56-4d5a-bbb4-35a41a2ca48c.png) + ```console + $ gh valet migrate jenkins --target-url https://github.com/:owner/:repo --output-dir tmp/migrate --source-url http://localhost:8080/job/monas_dev_work/job/monas_freestyle + [2022-08-20 22:08:20] Logs: 'tmp/migrate/log/valet-20220916-014033.log' + [2022-08-20 22:08:20] Pull request: 'https://github.com/:owner/:repo/pull/1' + ``` 3. Open the generated pull request in a new browser tab. @@ -38,7 +42,15 @@ Answer the following questions before running a `migrate` command: The first thing we should notice about the pull request is that there is a list of manual steps to complete: -![img](https://user-images.githubusercontent.com/19557880/186784161-b7882ac4-ac99-4462-b69f-f49b9202527b.png) +> Pipeline migrated from [Jenkins](http://localhost:8080/job/monas_dev_work/job/monas_freestyle) 🎉 +> +> ## Manual steps +> +> Perform the follow steps to complete the migration: +> +> ### monas_dev_work/monas_freestyle +> +> - [ ] Ensure secret is available: `${{ secrets.SECRET_TEST_EXPRESSION_VAR }}` Next, review the workflow you are adding by clicking on the `Files changed` tab. This is where you double check that everything looks good. If it didn't, you could push commits with the required changes, prior to merging. diff --git a/jenkins/readme.md b/jenkins/readme.md index a8e78c7..aa4ab40 100644 --- a/jenkins/readme.md +++ b/jenkins/readme.md @@ -12,48 +12,50 @@ These steps **must** be completed prior to starting other labs. 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. + - 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 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). -- Run the following command in the codespace's terminal: + - Run the following command in the codespace's terminal: - ```bash - gh valet version - ``` + ```bash + gh valet version + ``` -- Verify the output is similar to below. - - ```bash - gh version 2.14.3 (2022-07-26) - gh valet github/gh-valet v0.1.12 - valet-cli unknown - ``` + - Verify the output is similar to below. - - If `gh valet version` did not produce similar output, refer to the troubleshooting [guide](#troubleshoot-the-valet-cli). + ```console + $ gh valet version + gh version 2.14.3 (2022-07-26) + gh valet github/gh-valet v0.1.12 + valet-cli unknown + ``` + + - If `gh valet version` did not produce similar output, refer to the troubleshooting [guide](#troubleshoot-the-valet-cli). ## 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. +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: + - Run the following command from the codespace's terminal to start a Jenkins server: - ```bash - ./jenkins/bootstrap/setup.sh - ``` + ```bash + ./jenkins/bootstrap/setup.sh + ``` -- 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 the URL listed under the `Local Address` and click the `Open in Browser` tab. + - 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 the URL listed under the `Local Address` and click the `Open in Browser` tab. 2. Open the Jenkins server in your browser and use the following credentials to authenticate: - - Username: `admin` - - Password: `password` + - Username: `admin` + - Password: `password` -- Once authenticated, you should see a Jenkins server with a few predefined pipelines. +3. Once authenticated, you should see a Jenkins server with a few predefined pipelines. ## Labs for Jenkins @@ -61,10 +63,10 @@ Perform the following labs to learn more about Actions migrations with Valet: 1. [Configure credentials for Valet](1-configure.md) 2. [Perform an audit of a Jenkins server](2-audit.md) -3. [Perform a dry-run migration of a Jenkins pipeline](3-dry-run.md) -4. [Use custom transformers to customize Valet's behavior](4-custom-transformers.md) -5. [Perform a production migration of a Jenkins pipeline](5-migrate.md) -6. [Forecast potential build runner usage](6-forecast.md) +3. [Forecast potential build runner usage](3-forecast.md) +4. [Perform a dry-run migration of a Jenkins pipeline](4-dry-run.md) +5. [Use custom transformers to customize Valet's behavior](5-custom-transformers.md) +6. [Perform a production migration of a Jenkins pipeline](6-migrate.md) ## Troubleshoot the Valet CLI @@ -79,7 +81,8 @@ The CLI extension for Valet can be manually installed by following these steps: - Verify the result of the install contains: - ```bash + ```console + $ gh extension install github/gh-valet ✓ Installed extension github/gh-valet ```