Getting started with Cilicon self-hosted CI on Apple silicon

• cilicon
• continuous-integration

Cilicon, a macOS application developed by Trade Republic, uses Apple’s Virtualization Framework to create, allocate, and execute ephemeral CI (Continuous Integration) virtual machines with near-native performance. The underlying concept of Cilicon follows a simple cycle:

1. Duplicate Image Cilicon rapidly replicates the Virtual Machine bundle (folder) for each run, using APFS’s cloning feature for swift handling, even with large bundles.

2. Provision Shared Folder Depending on the chosen provisioner, Cilicon populates the bundle’s resources folder with files essential for the guest OS. For example, the GitHub Actions provisioner equips the image with the runner download URL, registration token, name, and labels. The process provisioner executes a specified executable during both the provisioning and de-provisioning stages. If needed, provisioners can be omitted by setting the type to “none,” suitable for services like Buildkite using non-expiring registration tokens.

3. Start Virtual Machine Cilicon initiates the virtual machine and automatically mounts the resources folder of the bundle on the guest OS.

4. Listen for Shutdown Cilicon actively monitors shutdown signals from the guest OS. Upon shutdown, it removes the used image, preparing for a fresh start.

Cilicon uses the tart container format and integrates an OCI client to fetch images from the internet. The tool currently supports GitHub Actions, Buildkite Agent, GitLab Runner, and arbitrary scripts.

Before you start

To complete the actions presented below, you must have:

• A Scaleway account logged into the console
• A Mac mini

Installing Cilicon on macOS

1. Connect to your Mac Mini using VNC.
2. Download the latest release of Cilicon.
3. Move the file Cilicon.app to the applications folder of your OS.
4. Add Cilicon.app as a launch item and set up automatic login.
   • Disable automatic software updates and any screen lock, battery-saving features, etc. to avoid issues with your Cilicon machine.
   • Cilicon expects a cilicon.yml configuration file in the host OS’s home directory. Refer to the official documentation for available settings.

Cilicon configuration

Cilicon uses YAML configuration files for settings, expected to be in a cilicon.yml file in the host OS’s home directory.

GitHub Actions provisioner

To use the GitHub Actions provisioner, create and install a new GitHub App with Self-hosted runners Read & Write permissions on the organization level. Download the private key file and reference it in the configuration file.

source: oci://ghcr.io/cirruslabs/macos-ventura-xcode:14.3.1
provisioner:
  type: github
  config:
    appId: <APP_ID>
    organization: <ORGANIZATION_SLUG>
    privateKeyPath: ~/github.pem

GitLab Runner provisioner

To use the GitLab Runner provisioner, create a runner with an authentication token.

Here is a basic example:

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

Or refer to a full configuration:

source: oci://ghcr.io/cirruslabs/macos-ventura-xcode:14.3.1
provisioner:
  type: gitlab
  config:
    gitlabURL: <GITLAB_INSTANCE_URL>
    runnerToken: <RUNNER_TOKEN>
    executor: <EXECUTOR> # defaults to 'shell'
    maxNumberOfBuilds: <MAX_BUILDS> # defaults to '1'
    downloadLatest: <DOWNLOAD_LATEST> # defaults to 'true'
    downloadURL: <DOWNLOAD_URL> # defaults to GitLab official Object Storage bucket
    configToml: >
      <CONFIG_TOML> # Advanced config as custom config.toml file to be appended to the basic config and copied to the runner.

Buildkite Agent provisioner

To use the Buildkite Agent provisioner, set your agent token in the provisioner config.

source: oci://ghcr.io/cirruslabs/macos-ventura-xcode:14.3.1
provisioner:
  type: buildkite
  config:
    agentToken: <AGENT_TOKEN>

Script provisioner

If you want to run a script (e.g. to start a runner that is not natively supported), use the script provisioner.

source: oci://ghcr.io/cirruslabs/macos-ventura-xcode:14.3.1
provisioner:
  type: script
  config:
    run: |
      echo "Hello World"
      sleep 10

Conclusion

This tutorial gives basic guidance for setting up and configuring provisioners for various CI platforms, enabling the use of this powerful macOS application for Continuous Integration (CI) on Apple silicon. For those seeking to further customize and optimize their Cilicon experience, it is strongly recommended to consult the official documentation to learn about advanced configurations, troubleshooting, and keeping you informed about any new features or updates.

For a more in-depth exploration of practical tips, use cases, and a thorough exploration of Cilicon’s capabilities, the article on Medium titled “Self-Hosted CI on Apple Silicon with Cilicon” provides additional perspectives and real-world implementation scenarios, empowering you to maximize the potential of Cilicon in your CI workflows.