Accessing macOS build worker via VNC

AppVeyor starts every macOS build in a clean isolated VM. While you can access macOS via SSH sometimes a better way to troubleshoot a broken build could be looking into macOS VM via VNC. During the build, you have full “root” access to that VM.

To enable VNC access during the build, you should configure two environment variables (either in appveyor.yml or on Environment tab of project settings):

  • APPVEYOR_VNC_PASSWORD - Set RDP password. This variable is optional, with default value generated for the current build worker.
  • APPVEYOR_VNC_BLOCK - if set to true, the build will be blocked until Delete me to continue build.txt file is deleted from user’s Desktop; otherwise, the build will continue. This variable is optional, with default value false.

Despite the fact appveyor.yml settings take over the UI, environment variables are handled differently, i.e. environment variables defined on UI are merged with those defined in appveyor.yml.

Add the following Bash command at the place where VNC access should be enabled:

curl -sflL '' | bash -e -

For example, to enable VNC access at the very beginning of the build, during init phase:

  APPVEYOR_VNC_PASSWORD: <your password>

  - sh: curl -sflL '' | bash -e -

VNC connection details for the current build worker will be displayed and build will continue. Displaying VNC connection details during init phase helps troubleshooting stuck builds.

If you need to investigate worker on build finish, add export APPVEYOR_VNC_BLOCK=true to display VNC connection details and pause the build until a special “lock” file on VM user home directory is deleted:

  - sh: export APPVEYOR_VNC_BLOCK=true
  - sh: curl -sflL '' | bash -e -

Alternatively, you can add sh: sleep 60m to postpone finishing a script so that you have more time to investigate with VNC.

VNC session is limited by overall build time (60 min).

Accessing MacOS build worker via SSH

Accessing MacOS build worker via SSH is similar to accessing Linux build worker.

Did you know that you can edit this page on GitHub and send us a Pull Request?