macOS Screen Share to GitHub hosted runner

instructions.md

Screen Share to macOS actions runner

Sometimes it is useful to have full access to macOS aqua session on github actions runner, for example to debug UI tests.

Requirements

ngrok account - free signup https://ngrok.com save your authtoken from https://dashboard.ngrok.com/get-started/your-authtoken we will refer to it as <NGROK_AUTH_TOKEN> below

Instructions

Connect to the action runner

1. add tmate step to your github workflow, see https://github.com/marketplace/actions/debugging-with-tmate

      - name: Debugging with tmate
        uses: mxschmitt/action-tmate@v3.11

2. launch workflow and wait for tmate action to print ssh command to the log output
3. login via ssh to the action runner by executing the above command, e.g. ssh K6GdVxZTvM4PMpK3uW8HAXypN@nyc1.tmate.io

On the runner

1. brew install ngrok
2. ngrok authtoken <NGROK_AUTH_TOKEN> replace with your ngrok token
3. notice ngrok runs successfully and prints tcp connection string, e.g. tcp://8.tcp.ngrok.io:19482

Session Status                online                                           
Version                       2.3.40                                           
Region                        United States (us)                               
Web Interface                 http://127.0.0.1:4040                            
Forwarding                    tcp://8.tcp.ngrok.io:19482 -> localhost:5900     

Open another tmate window

Press Ctrl-B then %

In another window

1. sudo passwd set root password to something like password
2. allow screen share connections sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/Resources/kickstart -activate -configure -allowAccessFor -allUsers -privs -all -clientopts -setmenuextra -menuextra yes
3. set screen resolution /Library/Application\ Support/VMware\ Tools/vmware-resolutionSet 1920 1080

On your Mac

open vnc://8.tcp.ngrok.io:19482 open screen share replacing connection string with above from ngrok

login with username root, use above set password, e.g. password

Screen Share

To close

Cancel github runner workflow. It will recycle runner's instance closing Screen Share connection and tmate session.