Running a build in a clean, virtualized CI environment is the ultimate test to ensure that your code doesn’t contain any hidden bugs that go unnoticed when you develop and build locally. From time to time, you will see the CI service doing its job and failing the build. However, sometimes the error message and the build logs alone are not enough and you would need more details to fix the issues.
Instead of trying to guess where things went wrong, you can take a look at what’s going on under the hood by establishing an SSH connection to the machine where the build is running.
How SSH access works
All our virtual machines are located in a private network. In order to allow users to connect to the virtual machine that’s running their build, Codemagic creates a temporary SSH tunnel through the public gateway. Each time you start a build, we generate a unique SSH key which is valid for the duration of the build. Once you access the VM during the build process, you’ll have 20 extra minutes after all build steps are completed or until the maximum build duration limit is reached to explore the entire VM. After the time is up, the SSH tunnel and the unique key are removed.
Establishing SSH connection
Establishing an SSH connection to the virtual machine is possible only for manually triggered builds. Setting it up requires both enabling the SSH mode in UI and running an automatically generated script in your terminal.
- In your app settings, click Start new build.
- In the Specify build configuration popup, check Enable SSH access and start the build.
![]()
- When the build has started, you will shortly see additional instructions for establishing SSH access. Run the automatically generated script in the terminal before the build finishes to establish an SSH connection to the builder machine.
![]()
If you don’t run the script before the build finishes, the unique SSH key expires and can’t be used anymore. A new script will be generated every time you run the build, so previous scripts cannot be reused.
Note that the script for establishing SSH connection works natively on Linux and MacOS, but requires additional software like Git-bash on Windows.
Debugging builds via SSH
Once you have established the SSH connection to the VM, you can interact with it and reproduce all commands run during the build. For example, you can debug your custom scripts that may run fine locally but fail in the CI environment that has a different setup. SSH access is also useful for testing connectivity to external services and troubleshooting third-party integrations.
Here’s an extra bonus to developers who don’t have a Mac at hand: by establishing remote access to the VM, you can debug your iOS builds or set up CocoaPods without a physical Mac device of your own.
To help you get started, we have put together a list of tips that you may find helpful when debugging builds on Codemagic:
-
You can access your project on the builder machine by running
cd $CM_BUILD_DIR -
If you encounter an error during the build, a good way to get started is by digging into the build logs on Codemagic and rerunning the first failed command.
-
The command
printenvprints all the environment variables exported during the build. Take a look at our documentation to see some of Codemagic read-only environment variables explained. -
The
sudocommand is available so you can execute all commands with root privileges. -
During an active SSH session, you can rerun the build with a different configuration right from the terminal.
-
Before terminating the connection, you can copy-paste the contents of the terminal window to keep a record of your actions on the builder machine.
Conclusion
The option to explore the VM via SSH gives you a better understanding of the processes running during the CI job, which means spending less time tracking down the issues. Take advantage of this feature to increase your green build rate and boost your development productivity. Read more about accessing the builder machine via SSH in our documentation.
