Bitrise Remote Access into MacOS environment with github.com/bitrise-steplib/steps-remote-access-macos-ngrok step

README.md

Remote Access a MacOS bitrise.io environment

Intro

If you need remote access (SSH & Screen Sharing / Remote Desktop right now) to a bitrise.io MacOS environment, you can use the https://github.com/bitrise-steplib/steps-remote-access-macos-ngrok step to do it.

This step is not shared in the base Bitrise StepLib, so you'll have to use it via the git:: reference.

Furthermore this step, at the time of writing, requires an ngrok.com account. We plan to provide an improved solution in the future which will no longer require a separate account.

Setup

To add the step into your app's bitrise.io workflow:

1. Open the app on bitrise.io
2. Open the Workflow Editor (Workflow tab)
3. Switch to bitrise.yml mode/tab in the editor
4. Then add the step to the workflow you want to debug, to the place where you want to "stop" the build:

steps:
    # steps here, e.g. git-clone; the ones you want to run before connecting to the build machine

    - git::https://github.com/bitrise-steplib/steps-remote-access-macos-ngrok.git@master: {}

    # any other step in the workflow; those **will not** run, the remote-access step will block for the rest of the build time

Once the step is in the yml Save it, and you can now even switch back to the Workflows tab and edit it via the GUI instead of the YML mode.

Configuration

There's only one required configuration option, the ngrok.com access token.

You'll also have to provide configs for either the SSH or the VNC (remote desktop) input, but you don't have to provide config for both. If you only provide the SSH config then only SSH access will be configured / enabled, or if you only provide the VNC config then only remote desktop will be enabled. You can of course provide both in which case both will be enabled.

Once you set the ngrok authtoken and at least the SSH or the VNC config simply save the config in the workflow editor and start a build (with the workflow which includes the remote-access step). The build will stop at the github.com/bitrise-steplib/steps-remote-access-macos-ngrok step, it will print the SSH & VNC (Screen Sharing) connection infos in the build log, and will keep the connection alive so that you can connect to it and test anything you like.

Ngrok Auth Token

First of all you'll have to create an ngrok.com account, to be able to "tunnel" through the environment (build VMs are running in a private network which is not accessible from the outside by default).

Once you have the ngrok.com account you'll have to provide the auth token from there. As you can see in the step's description: "Once you registered an account on ngrok go to the Auth menu, you can find your Ngrok Authtoken there."

Simply copy this authtoken and either paste it into the Ngrok Authtoken input of the step, or set a Secrets env var in the editor:

• key: NGROK_AUTH_TOKEN
• value: the ngrok authtoken from https://dashboard.ngrok.com/auth

VNC / Remote Desktop / Screen Sharing configuration

This one is really simple. To enable Screen Sharing / VNC / Remote Desktop simply set the related User and Screen Share password input of the step.

Either set the password directly in the step input, or set Secrets env var in the editor:

• key: USER_AND_SCREEN_SHARE_PASSWORD
• value: the password you want to use for VNC / Screen Sharing

SSH

If you want to ssh into the build virtual machine you'll have to provide an SSH public key. You'll be able to ssh into the virtual machine using the private key pair of the public key.

• If you want to generate a temporary keypair you can do it the way described in the input's description: ssh-keygen -t rsa -b 4096 -P '' -f ./bitrise-ssh . If you use this command then bitrise-ssh.pub will be the public key and bitrise-ssh will be the private key.
• Alternatively you can also use your own public SSH key from your Mac so that you don't have to generate a new one for the testing session. Simply copy the content of ~/.ssh/id_rsa.pub (HOME directory, in that .ssh hidden directory, and in that directory the id_rsa.pub file).
  • If you're on a Mac you can copy this pub key right to your Clipboard with: cat ~/.ssh/id_rsa.pub | pbcopy, then simply paste the value wherever you want.

Once you have the SSH public key you want to use you can either set it in the step's SSH public key input on the GUI, or set Secrets env var in the editor:

• key: SSH_PUBLIC_KEY
• value: the SSH public key (something like ssh-rsa AAA...t username@something.local)

Tips & Tricks

• This step will stop the build at the place where it runs.
  • In practice this means that e.g. if you add this step after the Git Clone step then the build will run up until the Git Clone step, and once the Git Clone step finishes and the remote-access-macos-ngrok step runs the build will not proceed, so the source code will be in the environment but nothing else will be performed.
  • If you add the step to the very end of the workflow, as the last step, then the build will proceed as usual, performing every step then will stop at the very end keeping the VM around (once a build is "finished" the build VM is always destroyed).
• If you're on a Mac and you use the default Screen Sharing app to remote desktop into the VM: you can drag-and-drop files from your Mac into the Screen Sharing app to transfer them to the VM. Clipboard is also shared (can be enabled in the Screen Sharing app's config if you disabled it), so you can also copy paste codes from your Mac into the Virtual Machine, as well as you can copy from the VM to your Mac (same for files, you can transfer files from the VM to your Mac with drag-and-drop).
• If you want to run your build inside the VM you can use the Bitrise CLI. This is the exact same CLI you can download on your own Mac/Linux, and the builds running on bitrise.io are performed via this CLI too. A practical intro to the CLI if you're not familiar with it: https://discuss.bitrise.io/t/how-to-experiment-with-bitrise-configs-locally-on-your-mac-linux/1751
  • Important note: the build VM is configured with CI mode enabled by default, and with a specified BITRISE_SOURCE_DIR. If you stop the build after the Git Clone step it's usually better to run the CLI in non CI mode, just like you would run it on your own Mac/PC (where you already have the code too). To do that, instead of bitrise run ... use env CI=false BITRISE_SOURCE_DIR="$(pwd)" bitrise run .... This will turn off the CI mode and will set the Source Code Dir to the directory where you run this command from.

• To stop the remote access / build simply Abort the build on the build's page, or shut down the virtual machine.