How do I connect to a macOS container via VNC?

Overview

When troubleshooting macOS builds, sometimes it can be useful to find out what's happening on screen in the macOS GUI. This can be done by ensuring that VNC is enabled in the host OS, and setting up the credentials with which to connect to the host.

Note: It is not possible to know the password for the default user. As such this method creates a new user from where you can VNC into the session and run any commands from there.

To connect to a MacOS container using the macOS Orb:

• Set up your desired VNC password in an environment variable or context variable named MAC_ORB_VNC_PASSWORD
• Implement the macOS orb v. >2.3.0 into your project's config.yml:

orbs:
  mac: circleci/macos@2.3.0

jobs:
  build:
    steps:
      - mac/enable-vnc

• Install a VNC viewer:
  • macOS users can use the Screen Sharing app
  • Linux and Windows users can download and install TightVNC or RealVNC Viewer
• Configure SSH port forwarding on your local machine:
  • ssh -p 54782 <mac container ip> -L5901:localhost:5900 -N
• Connect to the VNC session from your VNC client:
  • Connect to localhost:5901
  • Use credentials vncuser and the password you set in MAC_ORB_VNC_PASSWORD

Tip: You can find more information on the macOS Orb documentation page.