diff --git a/.gitignore b/.gitignore
index d155dc5..c05f815 100644
--- a/.gitignore
+++ b/.gitignore
@@ -351,4 +351,6 @@ MigrationBackup/
# valet files
.env*local
-credentials_file.yaml
\ No newline at end of file
+credentials_file.yaml
+
+.vscode
\ No newline at end of file
diff --git a/gitlab/3-dry-run.md b/gitlab/3-dry-run.md
index a57f413..fbb8c46 100644
--- a/gitlab/3-dry-run.md
+++ b/gitlab/3-dry-run.md
@@ -252,5 +252,3 @@ As an added challenge, try constructing and running the `dry-run` command yourse
## Next lab
[Use custom transformers to customize Valet's behavior](./4-custom-transformers.md)
-
-
diff --git a/gitlab/4-custom-transformers.md b/gitlab/4-custom-transformers.md
index cbf4363..72184c6 100644
--- a/gitlab/4-custom-transformers.md
+++ b/gitlab/4-custom-transformers.md
@@ -1,25 +1,30 @@
# Using custom transformers to customize Valet's behavior
-In this lab we want to do a `dry-run` of the `terraform-example` project. We can now perform a `dry-run` of this project, however, we have discovered that the output will need to be customized to transform the Terraform artifact report. After some research, we have determined that the `actions/upload-artifact` action will be an adequate substitute for it. Additionally, we will need to change the environment variable `PLAN_JSON` to use a different value: `custom_plan.json`. This customization will be present in many pipelines and an automated way to apply this would be ideal. In this lab, we will use the `--custom-transformers` flag to change the behavior of Valet using its DSL built on top of the Ruby language.
-- [Prerequisites](#prerequisites)
-- [Write Custom Transformers](#write-custom-transformers)
-- [Run with Custom Transformers](#run-with-custom-transformers)
-- [Next Lab](#next-lab)
+In this lab we will build upon the `dry-run` command to override Valet'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 Actions.
## Prerequisites
-1. Followed [steps](../gitlab#readme) to set up your codespace environment.
-2. Completed the [configure lab](../gitlab/valet-configure-lab.md)
-3. Completed the [dry-run lab](../gitlab/valet-dry-run-lab.md)
+1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your Codespace environment and start you GitLab server.
+2. Completed the [configure lab](./1-configure-lab.md#configuring-credentials).
+3. Completed the [dry-run lab](./3-dry-run.md).
-## Write Custom Transformers
-1. Run the `dry-run` command to see what information we can get from the generated action yaml.
+## Perform a dry-run
+
+We 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 gitlab --output-dir tmp --namespace valet --project terraform-example
+gh valet dry-run jenkins gitlab --output-dir tmp --namespace valet --project terraform-example
```
-2. Open the resulting GitHub Actions workflow by navigating to `tmp/valet/custom-transformer.yml` from the explorer
+The converted workflow that is generated by the above command can be seen below:
+
+
+ Converted workflow π
```yaml
name: valet/custom-transformer
@@ -45,45 +50,36 @@ jobs:
- run: terraform show --json $PLAN | convert_report > $PLAN_JSON
# # 'artifacts.terraform' was not transformed because there is no suitable equivalent in GitHub Actions
```
-3. We can see from the last line that `artifacts.terraform` was not transformed. In order for us to write a custom transformer for this we need to know the identifier. In general, the identifier will be the value between the backticks, which in this case is `artifacts.terraform`. This is how our custom transformer will target the correct step.
-4. The custom transformers file can have any name, but it is recommended that you use an `.rb` extension so the codespaces editor knows it is a ruby file and can provide syntax highlighting.
+
-5. we have chosen the `actions/upload-artifacts` as our replacement so we should look at the action's [documentation](https://github.com/marketplace/actions/upload-a-build-artifact) to determine the correct final yaml
+_Note_: You can refer to the previous [lab](./3-dry-run.md) to learn about the fundamentals of the `dry-run` command.
-```yaml
-- uses: actions/upload-artifact@v3
- with:
- path: VALUE_FROM_GITLAB
+## Custom transformers for an unknown step
+
+The converted workflow above contains an `artifacts.terraform` step was not automatically converted. We will need to answer the following questions before writing a custom transformer:
+
+1. What is the "identifier" of the step to customize?
+ - __artifacts.terraform__
+
+2. What is the desired Actions syntax to use instead?
+ - After some research, we have determined that the following bash script will provide similar functionality:
+
+ ```yaml
+ - uses: actions/upload-artifact@v3
+ with:
+ path: VALUE_FROM_GITLAB
+ ```
+
+Now we can begin to write the custom transformer. Customer 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
+code transformers.rb
```
-6. Now that we know the final yaml needed for the transformer, we can start to write the ruby file. In the custom transformers file we will call the `transform` method. This is a special method that Valet exposes, that takes the identifier we determined earlier and returns a ruby Hash of the final YAML for the pipeline. The ruby Hash can be thought of as the JSON representation of the YAML we want. Valet will call that method when it encounters the identifier and pass in an `item`. The `item` is the values defined for that step in GitLab. In this case the item is the path of the terraform report.
-
- ```ruby
- transform "artifacts.terraform" do |item|
- {
- uses: "actions/upload-artifact@v2",
- with: {
- path: item
- }
- }
- end
- ```
-
- - Note: If you were unsure what `item` represents, you could use some basic ruby to print `item` to the terminal. You can achieve this by adding the following line in the transform method:
- `puts "This is the item: #{item}"`
-
-7. The custom transformers file also lets you replace values of `variables` by using the `env` method. Letβs replace the value for `PLAN_JSON` by using the below line. The first value of the `env` method is the target variable name and the second is the new value to be used.
+Next, we will define a `transform` method for the `sleep` identifier by adding the following code to `transformers.rb`:
```ruby
-env "PLAN_JSON", "custom_plan.json"
-```
-
-8. Create a new file in the root of the workspace called `transformers.rb` with the following contents
-
-```ruby
-env "PLAN_JSON", "custom_plan.json"
-
transform "artifacts.terraform" do |item|
{
uses: "actions/upload-artifact@v2",
@@ -94,14 +90,15 @@ transform "artifacts.terraform" do |item|
end
```
-## Run Again with Customer Transformers
-1. Run the `dry-run` with our custom transformer by adding the `--custom-transformers` option followed by the path of the custom transformer ruby file
+This method can use any valid ruby syntax and should return a `Hash` that represents the YAML that should be generated for a given step. Valet will use this method to convert a step with the provided identifier and will use the `item` parameter for the original values configured in GitLab.
+
+Now, we 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 gitlab --output-dir tmp --namespace valet --project terraform-example --custom-transformers transformers.rb
+gh valet dry-run jenkins gitlab --output-dir tmp --namespace valet --project terraform-example --custom-transformers transformers.rb
```
-2. Verify the custom transformer worked and now you have the `upload-artifact` in the place of the unsupported result.
+The converted workflow that is generated by the above command will now use the custom logic for the `artifacts.terraform` step.
```diff
- # # 'artifacts.terraform' was not transformed because there is no suitable equivalent in GitHub Actions
@@ -110,7 +107,27 @@ gh valet dry-run gitlab --output-dir tmp --namespace valet --project terraform-e
+ path: "$PLAN_JSON"
```
-3. Verify that `PLAN_JSON` env has been updated to `custom_plan.json`
+_Note_: If you were unsure what the data structure of `item` was then you could use the following code in the custom transformer to print `item` to the console:
+
+```ruby
+transform "artifacts.terraform" do |item|
+ puts item
+end
+```
+
+## Custom transformers for environment variables
+
+We can also use custom transformers to edit the values of environment variables in converted workflows. In our example, we will be updating the `PLAN_JSON` environment variable to be `custom_plan.json` instead of `plan.json`.
+
+To do this, add the following code to the `transformers.rb` file.
+
+```ruby
+env "PLAN_JSON", "custom_plan.json"
+```
+
+In this example, the first parameter to the `env` method is the environment variable name and the second is the updated value.
+
+Now, we can perform another `dry-run` command with the `--custom-transformers` CLI option. When you open the converted workflow the `PLAN_JSON` environment variable will be set to `custom_plan.json`:
```diff
env:
@@ -119,9 +136,31 @@ gh valet dry-run gitlab --output-dir tmp --namespace valet --project terraform-e
+ PLAN_JSON: custom_plan.json
```
-Now that you have a custom transformers file you can add additional `transform`and `env` methods as needed and reuse it while running other `dry-run` and `migrate` commands.
+At this point of the lab the file contents of `transformers.rb` should match this:
-Note: The custom transformers will only affect the pipeline being transformed if they contain the matching identifiers. If you believe a custom transformer should have altered the output, double check that the identifier is correct.
+
+ Custom transformers π
-## Next Lab
-[Forecast GitLab Usage](../gitlab/5-forecast.md)
+```ruby
+ env "PLAN_JSON", "custom_plan.json"
+
+ transform "artifacts.terraform" do |item|
+ {
+ uses: "actions/upload-artifact@v2",
+ with: {
+ path: item
+ }
+ }
+ end
+```
+
+
+
+Thats it! Congratulations you have overridden Valet's default behavior by customizing the conversion of:
+
+- Unknown steps
+- Environment variables
+
+## Next lab
+
+[Perform a production migration of a GitLab pipeline](5-migrate.md)
\ No newline at end of file
diff --git a/jenkins/4-custom-transformers.md b/jenkins/4-custom-transformers.md
index 244e7a7..b9d28ba 100644
--- a/jenkins/4-custom-transformers.md
+++ b/jenkins/4-custom-transformers.md
@@ -17,11 +17,11 @@ In this lab we will build upon the `dry-run` command to override Valet's default
We 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 -o tmp/jenkins/dry-run
- ```
+```bash
+gh valet dry-run jenkins --source-url http://localhost:8080/job/test_pipeline -o tmp/jenkins/dry-run
+```
-The converted workflow that is generated by the above command can be seen below
+The converted workflow that is generated by the above command can be seen below:
Converted workflow π