Orka Integrations: GitLab CI/CD with MacStadium's Orka

GitLab CI/CD is a powerful tool for Mac and iOS CI, and it doesn’t require a third-party build server. We’re taking you through everything you need to get the our GitLab CI/CD plugin running on your Orka instance.

Orka and GitLab logo

GitLab CI/CD is a powerful tool for modern Mac and iOS CI. It is baked into the GitLab experience, so no third-party build server, such as Jenkins, is required to achieve continuous integration. Moreover, GitLab has made it simple to visualize your build pipeline with its CI/CD UI, as shown here.

Orka is a unique, enterprise-ready, Mac virtualization platform that utilizes Kubernetes and Docker under the hood, and exposes certain features of these tools to end-users.

In addition to GitLab's dedicated bank of shared runners, GitLab offers a "specific runner" - that is, a runner stood up by the user and tied specifically to a given project. Today, we'll look at standing up a specific runner for a GitLab project in MacStadium's Orka.

GitLab ‘Specific Runner’ in Orka for Static Mac and iOS CI

This is the best of both worlds. GitLab's shared runners only offer a relatively small amount of compute resources, which will likely be exhausted quickly each month by an active development team. Moreover, running continuous integration jobs on a public server leaves far too much to chance for most teams in production, because there is the hanging question of what else is running on those servers.

Setting up a specific runner in a private Mac cloud, such as Orka offers, is a clean and efficient solution to both of these problems.

Install and Register a Static ‘GitLab Specific Runner’ in Orka

In order to get everything up and running, you’ll need to perform the following steps via the Mac Terminal GUI.

First, create an Orka VM. Then run the following to get connection details for your VM.

orka vm list

Result of Orka VM List - Showing a node named gitlab-runner with a screen share port of 5900 highlighted.

To gain GUI access to the terminal app on an Orka VM, you’ll need to start an Apple Screenshare session by opening the Finder on your local machine and then pressing “Command K.” Then, you will be prompted for your VM credentials.

macOS connect to server screen

macOS server authentication screen

Once you’ve made the screen-sharing connection, log into the VM and open the Terminal app.

Then, in that terminal session, install Homebrew by running:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then, install the GitLab Runner, like so:

brew install gitlab-runner

Screenshot that says: Set up a specific Runner manually. 1. Install GitLab Runner 2. Specify the following URL during the Runner setup: https://gitlab.com 3. Use the following registration token during setup: <redacted> 4. Start the runner

Get the runner registration token from GitLab and register it. You can find the registration token for a specific project by navigating to the project, and in the sidebar, navigate to Settings>CI/CD. Then click the Runners button, and copy the token, like so:

Orka-iMac:~ admin$ gitlab-runner register
Runtime platform arch=amd64 os=darwin pid=2241 revision=8fa89735 version=13.6.0
WARNING: Running in user-mode.
WARNING: Use sudo for system-mode:
WARNING: $ sudo gitlab-runner...

Enter the GitLab instance URL (for example, https://gitlab.com/):
Enter the registration token:

Enter a description for the runner:
Enter tags for the runner (comma-separated):

Registering runner... succeeded runner=hGLA2r4X
Enter an executor: docker-ssh, virtualbox, kubernetes, docker-ssh+machine, custom, docker, parallels, shell, ssh, docker+machine:
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

NOTE: this approach will require that you choose an executor of type shell.

And finally, start the runner:

Orka-iMac:~ admin$ gitlab-runner run
Runtime platform arch=amd64 os=darwin pid=2291 revision=8fa89735 version=13.6.0
Starting multi-runner from /Users/admin/.gitlab-runner/config.toml... builds=0
WARNING: Running in user-mode.
WARNING: Use sudo for system-mode:
WARNING: $ sudo gitlab-runner...

Configuration loaded builds=0
listen_address not defined, metrics & debug endpoints disabled builds=0
[session_server].listen_address not defined, session endpoints disabled builds=0

Testing the GitLab Specific Runner’s Connection

Create a GitLab CI/CD YAML file called .gitlab-ci.yml in the root directory of your project.

To test your GitLab Specific Runner’s connection, simply go to your project’s repository, navigate to CI/CD>Pipelines and click “Run Pipeline.” If everything is communicating as it should, you will see your GitLab CI/CD job kick off on your new macOS VM running in Orka.


GitLab CI/CD is a free, powerful tool that alleviates the need for any third-party build tooling, such as Jenkins, and it integrates well with MacStadium compute resources for stable, secure Mac and iOS CI. Above, we looked at getting a static CI system hooked up. To learn about ephemeral setups, check out the documentation.