diff --git a/circle_ci/4-custom-transformers.md b/circle_ci/4-custom-transformers.md index caed142..fe2bdea 100644 --- a/circle_ci/4-custom-transformers.md +++ b/circle_ci/4-custom-transformers.md @@ -18,7 +18,7 @@ In this lab you will build upon the `dry-run` command to override Valet's defaul 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 -# ADD_COMMAND +gh valet dry-run circle-ci -o tmp/custom_transformers --circle-ci-project circleci-node-example ``` The converted workflow that is generated by the above command can be seen below: @@ -27,7 +27,35 @@ The converted workflow that is generated by the above command can be seen below: Converted workflow 👇 ```yaml -# ADD_YAML +name: labs-data/circleci-node-example/sample +on: + push: + branches: + - main +jobs: + setup: + runs-on: + - self-hosted + - large + env: + COVERAGE_DIR: "./tmp/cov" + steps: + - run: mkdir -p $COVERAGE_DIR + node_test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - id: npm-cache-dir + run: echo "::set-output name=dir::$(npm config get cache)" + - uses: actions/cache@v2 + with: + path: "${{ steps.npm-cache-dir.outputs.dir }}" + key: "${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}" + restore-keys: "${{ runner.os }}-node-" + - run: npm ci + - run: npm run test +# # This item has no matching transformer +# - codecov_codecov_upload: ``` @@ -36,7 +64,67 @@ _Note_: You can refer to the previous [lab](./3-dry-run.md) to learn about the f ## Custom transformers for an unknown step -ADD_CONTENT_OR_REMOVE +The converted workflow above contains an `codecov_codecov_upload` step that was not automatically converted. Answer the following questions before writing a custom transformer: + +1. What is the "identifier" of the step to customize? + - __codecov_codecov_upload__ + +2. What is the desired Actions syntax to use instead? + - After some research, you have determined that the [codecov action](https://github.com/marketplace/actions/codecov) in the marketplace will provide similar functionality: + + ```yaml + - uses: codecov/codecov-action@v3 + with: + token: ${{ secrets.CODECOV_TOKEN }} + ``` + +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 +code transformers.rb +``` + +Next, you will define a `transform` method for the `codecov_codecov_upload` identifier by adding the following code to `transformers.rb`: + +```ruby +transform "codecov_codecov_upload" do |_item| + { + name: "Upload coverage to Codecov", + uses: "codecov/codecov-action@v3", + with: { + token: "${{ secrets.CODECOV_TOKEN }}" + } + } +end +``` + +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 CircleCI. + +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 circle-ci -o tmp/custom_transformers --circle-ci-project circleci-node-example --custom-transformers transformers.rb +``` + +The converted workflow that is generated by the above command will now use the custom logic for the `codecov_codecov_upload` step. + +```diff +- # # This item has no matching transformer +- # - codecov_codecov_upload: ++ - name: upload coverage to Codecov ++ uses: codecov/codecov-action@v3 ++ with: ++ token: "${{ secrets.CODECOV_TOKEN }}" +``` + +_Note_: If you were unsure what the data structure of `item` was, you could use the following code in the custom transformer to print `item` to the console: + +```ruby +transform "codecov_codecov_upload" do |item| + puts item +end +``` + ## Custom transformers for environment variables