4.12. Working with Cilicon

The ns-3 project repository is currently hosted in GitLab, which includes continuous integration (CI) tools to automate build, tests, packaging and distribution of software. The CI works based on jobs, that are defined in YAML files and run inside containers.

While we can run most Linux containers everywhere without much problem, that is not the case for Windows and MacOS. You can run gitlab-runner as a local user, taking proper precautions to avoid that user from escalating privileges, then taking over your own network and other systems on it.

That is typically harder than just enforce network security, and virtualization-based security. GitLab doesn’t offer a way to do that, other than their own runners, which cost up to 6x more than linux ones. Which is why Trade Republic created the Cilicon application for MacOS, which creates an ephemeral virtual machine, executes a gitlab job, then destroys the VM, and creates a fresh new one.

To set it up, first go to System Settings->Energy and enable all options to prevent sleep, wake on network traffic, and restart after power failure (assuming the Mac will be used exclusively as a CI server).

After this, download the latest release in Cilicon releases. Put the application in Applications directory and start it. It will ask you to install MacOS virtualization framework.

If you only have a single CI runner that you wish to run, follow their easy settings and create a ~/cilicon.yml file at the user directory containing:

source: oci://ghcr.io/cirruslabs/macos-runner:sequoia
provisioner:
  type: gitlab
  config:
    gitlabURL: <GITLAB_INSTANCE_URL>
    runnerToken: <RUNNER_TOKEN>

If you have multiple CI runners that you wish to run from a single machine, one job at a time, you need a custom configuration file, first create a folder that will be shared with the VM.

mkdir /Users/nsnam/gitlab-ephemeral

Then add your GitLab runner config.toml file there, for example, containing:

concurrent = 1
check_interval = 0
connection_max_age = "15m0s"
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "MacOsRunnerForProjectA"
  url = "https://gitlab.com/"
  token = "<RUNNER_TOKEN_A>"
  executor = "shell"
  cleanup_policy = "always"

[[runners]]
  name = "MacOsRunnerForProjectB"
  url = "https://gitlab.com/"
  token = "<RUNNER_TOKEN_B>"
  executor = "shell"
  cleanup_policy = "always"

Then create a cilicon.yml file at the user directory containing:

source: oci://ghcr.io/cirruslabs/macos-sonoma-xcode:15
provisioner:
  type: script
  config:
    run: |
      cp /Volumes/My\ Shared\ Files/gitlab-runner/config.toml /Users/admin/.gitlab-runner/config.toml
      gitlab-runner run
consoleDevices:
  - tart-version-2
hardware:
  ramGigabytes: 20
  connectsToAudioDevice: false
directoryMounts:
  - hostPath: /Users/nsnam/gitlab-ephemeral
    guestFolder: gitlab-runner
    readOnly: true

Note: If you want to create a new VM for every CI job, replace gitlab-runner run with gitlab-runner run-single. Not very recommended, because it will hit SSD hard. And recent Macs have soldered storage.

After configuring everything, execute Cilicon. It will setup MacOS virtualization framework, then fetch the VM image. It will then start the VM.

At this point, MacOS will query you for being visible in network. You need to say yes, so the VM can access the shared directory.

Otherwise, you need to either write the TOML with the cilicon.yml, or download it from a remote server.

At this point, you should have your native MacOS runners fully working. Try starting a job and see if they respond via GitLab web interface.