Using Microsoft Dev Proxy in your GitHub Actions workflow on a macOS hosted VM

Lately, I have been working with the Microsoft’s Dev Proxy, a tool for API simulation, mocking, and testing. One of the things I wanted to try was to use the Dev Proxy in a GitHub Actions workflow so that I could use it in combination with Playwright to test my solutions with mocked APIs.

The Dev Proxy is a .NET Core application that can run on any platform that supports .NET Core, so it works on Windows, Linux, and macOS. I chose to use a macOS virtual machine/runner because, at the time of writing, the Dev Proxy cannot automatically trust the root certificate.

info

Currently there is an issue open on the Dev Proxy GitHub repository to add support for trusting the root certificate on macOS - Dev Proxy #601.

In this blog post, I will show you how to use the Dev Proxy in your GitHub Actions workflow on a macOS virtual machine.

important

Be aware of that jobs running on Windows and macOS runners that GitHub hosts consume minutes at 2 and 10 times the rate that jobs on Linux runners consume. You can read more about it in the GitHub Actions - Minute multipliers for hosted runners documentation section.

Installing the Dev Proxy

Let us start with installing the Dev Proxy on the macOS virtual machine. We can use the bash script provided in the Dev Proxy documentation for this. To include this into your GitHub Actions workflow, you can use the following step:

1
2

- name: Install Dev Proxy
  run: bash -c "$(curl -sL https://aka.ms/devproxy/setup.sh)"

Running the Dev Proxy as a background service

Once installed, you can run the Dev Proxy as a background service by adding an ampersand & at the end of the command.

info

You can read more about it in the #DevHack: Running a background service on GitHub Actions article.

Here is what the GitHub Actions step looks like:

1
2

- name: Run Dev Proxy
  run: ./devproxy/devproxy &

What about HTTPS endpoints?

When you start using the Dev Proxy like this on GitHub Actions, you will encounter issues when calling HTTPS endpoints. In my case, I got the following error when testing it with Playwright:

1

Error: page.goto: net::ERR_PROXY_CONNECTION_FAILED at https://frontmatter.codes/

These issues are normal because to intercept HTTPS traffic, you must trust the root certificate which gets created by the Dev Proxy. When you run the Dev Proxy on your local machine for the first time, it will prompt you to trust the root certificate.

Show image

As it runs in a non-interactive mode in GitHub Actions, you cannot trust the certificate that way. To solve this, we will have to include a couple of extra steps in our workflow to trust the root certificate and be able to intercept the HTTPS traffic.

Trusting the root certificate

When the Dev Proxy asks you to trust the root certificate, and you accept it, it uses the trust-cert.sh script to find the certificate and trust it.

My first attempt was to run the trust-cert.sh script in my GitHub Actions workflow. Unfortunately, this did not work because the security add-trusted-cert command requires a password to add the certificate to the login keychain.

After some research, I found an article about Trusting Certificates in System Keychain without Prompting. The article explains that you will not be prompted for a password when you add a certificate to the system keychain, and this will be our solution to make it work in our GitHub Actions workflow.

The script to trust the certificate in the system keychain looks as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

- name: Install the Dev Proxy's certificate
  timeout-minutes: 1
  run: |
    echo "Finding certificate..."
    security find-certificate -c "Dev Proxy CA" -a -p > dev-proxy-ca.pem

    echo "Trusting certificate..."
    sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain dev-proxy-ca.pem
    echo "Certificate trusted."

    # Set the system proxy settings (optional)
    echo "http_proxy=http://127.0.0.1:8000" >> $GITHUB_ENV
    echo "https_proxy=http://127.0.0.1:8000" >> $GITHUB_ENV

    # Required to test CURL with the Dev Proxy (optional)
    echo "SSL_CERT_FILE=$GITHUB_WORKSPACE/dev-proxy-ca.pem" >> $GITHUB_ENV    

This script is similar to the trust-cert.sh script, but instead of adding it to the login keychain, the certificate gets added to the system keychain.

At the end of the script there are three exports which are all optional.

• The http_proxy and https_proxy environment variables can be used to set the system proxy settings on the macOS virtual machine.
• The SSL_CERT_FILE environment variable is required on macOS to make the curl commands work with the Dev Proxy.

Show image

The complete GitHub Actions workflow

Now that we have the certificate trust figured out, we can combine all the steps into a complete GitHub Actions workflow.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

name: macOS Dev Proxy

on:
  push:
    branches:
      - main
      - dev
  workflow_dispatch:

jobs:
  test:
    timeout-minutes: 60
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4

      - name: Install Dev Proxy
        run: bash -c "$(curl -sL https://aka.ms/devproxy/setup.sh)"

      - name: Run Dev Proxy
        run: ./devproxy/devproxy &

      - name: Install the Dev Proxy's certificate
        timeout-minutes: 1
        run: |
          echo "Finding certificate..."
          security find-certificate -c "Dev Proxy CA" -a -p > dev-proxy-ca.pem

          echo "Trusting certificate..."
          sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain dev-proxy-ca.pem
          echo "Certificate trusted."

          # Set the system proxy settings (optional)
          echo "http_proxy=http://127.0.0.1:8000" >> $GITHUB_ENV
          echo "https_proxy=http://127.0.0.1:8000" >> $GITHUB_ENV

          # Required to test CURL with the Dev Proxy (optional)
          echo "SSL_CERT_FILE=$GITHUB_WORKSPACE/dev-proxy-ca.pem" >> $GITHUB_ENV          

      # Include the additional steps you want to run after the Dev Proxy started
      - name: Test Dev Proxy
        run: |
          curl -ix http://127.0.0.1:8000 https://jsonplaceholder.typicode.com/posts
          # When you used the system proxy settings, you don't need to specify the proxy in the curl command
          curl -i https://jsonplaceholder.typicode.com/posts          

Show image

With this setup, you can use the Dev Proxy in your GitHub Actions workflow on a macOS virtual machine. This allows you to use the Dev Proxy in combination with Playwright or any other tool for testing your solutions.

info

Templates are available on the following GitHub repository.