{"id":15099327,"url":"https://github.com/traderepublic/cilicon","last_synced_at":"2025-10-08T23:26:59.050Z","repository":{"id":64007817,"uuid":"562770907","full_name":"traderepublic/Cilicon","owner":"traderepublic","description":"🛠️ Self-Hosted ephemeral macOS CI on Apple Silicon","archived":false,"fork":false,"pushed_at":"2025-09-01T10:39:01.000Z","size":2868,"stargazers_count":1078,"open_issues_count":7,"forks_count":36,"subscribers_count":27,"default_branch":"main","last_synced_at":"2025-09-11T16:52:20.485Z","etag":null,"topics":["ci","github-actions","m1","m2","macos","self-hosted","self-hosted-runner","selfhosted","silicon","swift","swiftui","virtualization"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/traderepublic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-11-07T08:17:34.000Z","updated_at":"2025-09-10T12:42:04.000Z","dependencies_parsed_at":"2023-01-14T18:45:24.210Z","dependency_job_id":"298405e3-a7ab-4eae-aa48-e1cda2074db8","html_url":"https://github.com/traderepublic/Cilicon","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/traderepublic/Cilicon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traderepublic%2FCilicon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traderepublic%2FCilicon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traderepublic%2FCilicon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traderepublic%2FCilicon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/traderepublic","download_url":"https://codeload.github.com/traderepublic/Cilicon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traderepublic%2FCilicon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000736,"owners_count":26082862,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci","github-actions","m1","m2","macos","self-hosted","self-hosted-runner","selfhosted","silicon","swift","swiftui","virtualization"],"created_at":"2024-09-25T17:10:34.198Z","updated_at":"2025-10-08T23:26:59.044Z","avatar_url":"https://github.com/traderepublic.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\r\n\t\u003ca href=\"https://github.com/traderepublic/Cilicon/\"\u003e\u003cimg width=\"350\" src=\"https://user-images.githubusercontent.com/1622982/204773431-050cc008-029c-4ab1-98a6-9d4fc30d272d.png\" alt=\"Cilicon\" /\u003e\u003c/a\u003e\u003cbr /\u003e\u003cbr /\u003e\r\n\tSelf-Hosted macOS CI on Apple Silicon\u003cbr /\u003e\u003cbr /\u003e\r\n    \u003ca href=\"#-about-cilicon\"\u003eAbout\u003c/a\u003e\r\n  • \u003ca href=\"#-getting-started\"\u003eGetting Started\u003c/a\u003e\r\n  • \u003ca href=\"#-ideas-for-the-future\"\u003eIdeas for the Future\u003c/a\u003e\r\n  • \u003ca href=\"#-join-us\"\u003eJoin Us\u003c/a\u003e\r\n\u003c/p\u003e\r\n\r\n\u003e [!WARNING]\r\n\u003e There seems to be an issue with swift-nio based SSH on macOS 15.0-15.3.X. Please use macOS 15.4+ for a more reliable experience.\r\n\r\n\u003cdetails\u003e\u003csummary\u003e\u003ch3\u003e💥 What's new in 2.0?\u003c/h3\u003e\u003c/summary\u003e\r\nWe're excited to announce a new major update to Cilicon! Here's a summary of what's new:\r\n\u003cul\u003e\r\n        \u003cli\u003eWhile Cilicon 1.0 relied on a user-defined Login Item script in the VM, its new version now includes an SSH client and directly executes commands on the VM.\u003c/li\u003e\r\n        \u003cli\u003eCilicon has partially adopted the \u003ca href=\"https://github.com/cirruslabs/tart\"\u003etart\u003c/a\u003e image format and can automatically convert 1.0 images to it.\u003c/li\u003e\r\n        \u003cli\u003eThe integrated OCI client can download pre-built CI images that have been created with/for tart. We recommend their \u003ca href=\"https://github.com/cirruslabs/macos-image-templates/pkgs/container/macos-sonoma-xcode\"\u003emacos-sonoma-xcode\u003c/a\u003e images.\u003c/li\u003e\r\n\u003c/ul\u003e\r\n\u003ch4\u003eMigrating from 1.0\u003c/h4\u003e\r\n\u003cul\u003e\r\n        \u003cli\u003eThe config file schema has changed slightly. In most cases renaming the \u003ccode\u003evmBundlePath\u003c/code\u003e property to \u003ccode\u003esource\u003c/code\u003e should suffice.\u003c/li\u003e\r\n        \u003cli\u003eWhen Cilicon detects a 1.0 image it will offer you to automatically convert it to the new format for you.\u003c/li\u003e\r\n\t\u003cli\u003eWhen converting an image from the 1.0 format, you must enable SSH and set the respective credentials in the config (or use the default \u003ccode\u003eadmin:admin\u003c/code\u003e).\u003c/li\u003e\r\n\u003c/ul\u003e\r\n\u003c/details\u003e\r\n\r\n## 🔁 About Cilicon\r\n\r\nCilicon is a macOS App that leverages Apple's [Virtualization Framework](https://developer.apple.com/documentation/virtualization) to create, provision and run ephemeral CI VMs with near-native performance. It currently supports Github Actions, Buildkite Agent, GitLab Runner and arbitrary scripts. Depending on your setup, should be able to get up and running with your self-hosted CI in minutes 🚀\r\n\r\nCilicon operates in a very simple cycle described below:\r\n\r\n\u003ctable\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e\u003cimg width=\"500\" alt=\"Cilicon Cycle\" src=\"https://github.com/traderepublic/Cilicon/assets/1622982/0774ad39-4c86-4f23-ab27-5be4c89fa8f8\"\u003e\r\n\u003c/br\u003e\u003cp align=\"center\"\u003e\u003ci\u003eThe Cilicon Cycle\u003c/i\u003e\u003c/p\u003e\u003c/td\u003e\r\n    \u003ctd\u003e\u003cimg width=\"600\" alt=\"Cilicon Cycle\" src=\"https://github.com/traderepublic/Cilicon/assets/1622982/31a0e031-4938-4d42-bc75-6ee29269abe4\"\u003e\r\n\u003c/br\u003e\u003cp align=\"center\"\u003e\u003ci\u003eRunning a sample job via GitHub Actions (2x playback)\u003c/i\u003e\u003c/p\u003e\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n\u003c/table\u003e\r\n\r\n## 🚀 Getting Started\r\n\r\nTo get started, download the latest release [here](https://github.com/traderepublic/Cilicon/releases/latest).\r\n\r\n### ✨ Choosing a Source\r\n\r\nCilicon uses the `tart` container format and comes with an integrated [OCI](https://opencontainers.org/) client to fetch images from the internet.\r\n\r\nIt's recommended to use [publicly hosted images](https://github.com/cirruslabs/macos-image-templates/pkgs/container/macos-sonoma-xcode), however if you need to create or customize your own image, you may use [tart](https://github.com/cirruslabs/tart/).\r\n\r\n\r\n#### ⚠️ Important\r\n- When choosing an OCI hosted image, make sure to prepend the `oci://` scheme to the url. Cilicon will otherwise assume a local filesystem path.\r\n- Don't use the `latest` tag when choosing an image version. Instead pick the specific version of Xcode you would like to have installed (e.g. `14.3`).\r\n- Images downloaded via OCI will reside in the `~/.tart` folder which should be cleared of unused images periodically.\r\n- Images with newer versions of macOS may be published with the same version of Xcode installed. In case you want to upgrade, you may need to manually delete the outdated image and start Cilicon again.\r\n\r\n### ⚙️ Configuration\r\n\r\nCilicon expects a `cilicon.yml` file to be present in the Host OS's home directory.\r\nFor more information on all available settings see [Config.swift](/Cilicon/Config/Config.swift).\r\n\r\n#### GitHub Actions\r\n\r\nTo use the GitHub Actions provisioner you will need to [create and install a new GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) with `Self-hosted runners` `Read \u0026 Write` permissions on the organization level and download the private key file to be referenced in the configuration file.\r\n\r\n``` yml\r\nsource: oci://ghcr.io/cirruslabs/macos-runner:sequoia\r\nprovisioner:\r\n  type: github\r\n  config:\r\n    appId: \u003cAPP_ID\u003e\r\n    organization: \u003cORGANIZATION_SLUG\u003e\r\n    privateKeyPath: ~/github.pem\r\n```\r\n#### GitLab Runner\r\n\r\nTo use the GitLab Runner provisioner you will need to [create a runner with an authentication token](https://docs.gitlab.com/ee/ci/runners/runners_scope.html#create-a-shared-runner-with-an-authentication-token).\r\n\r\nMinimal example:\r\n\r\n``` yml\r\nsource: oci://ghcr.io/cirruslabs/macos-runner:sequoia\r\nprovisioner:\r\n  type: gitlab\r\n  config:\r\n    gitlabURL: \u003cGITLAB_INSTANCE_URL\u003e\r\n    runnerToken: \u003cRUNNER_TOKEN\u003e\r\n```\r\n\r\nFull configuration:\r\n\r\n``` yml\r\nsource: oci://ghcr.io/cirruslabs/macos-runner:sequoia\r\nprovisioner:\r\n  type: gitlab\r\n  config:\r\n    gitlabURL: \u003cGITLAB_INSTANCE_URL\u003e\r\n    runnerToken: \u003cRUNNER_TOKEN\u003e\r\n    executor: \u003cEXECUTOR\u003e # defaults to 'shell'\r\n    maxNumberOfBuilds: \u003cMAX_BUILDS\u003e # defaults to '1'\r\n    downloadLatest: \u003cDOWNLOAD_LATEST\u003e # defaults to 'true'. If 'false' it expects the binary to be present at the user's home directory\r\n    downloadURL: \u003cDOWNLOAD_URL\u003e # defaults to GitLab official S3 bucket\r\n    tomlPath: \u003cPATH_TO_TOML\u003e # defaults to `nil`. If set, it ignores the other runner related variables and passes the specified path to the runner executable\r\nconsoleDevices:\r\n  - tart-version-2\r\nsshConnectMaxRetries: \u003cSSH_CONNECT_MAX_RETRIES\u003e # defaults to 10\r\n```\r\n\r\n#### Buildkite Agent\r\n\r\nTo use the Buildkite Agent provisioner, simply set your agent token in the provisioner config.\r\n\r\n``` yml\r\nsource: oci://ghcr.io/cirruslabs/macos-runner:sequoia\r\nprovisioner:\r\n  type: buildkite\r\n  config:\r\n    agentToken: \u003cAGENT_TOKEN\u003e\r\n```\r\n\r\n#### Script\r\n\r\nIf you want to run a script (e.g. to start a runner that's not natively supported), you may use the `script` provisioner.\r\n\r\n``` yml\r\nsource: oci://ghcr.io/cirruslabs/macos-runner:sequoia\r\nprovisioner:\r\n  type: script\r\n  config:\r\n     run: |\r\n     \techo \"Hello World\"\r\n        sleep 10\r\n```\r\n\r\n#### Console Devices\r\n\r\nCilicon supports injecting console devices into the VM configuration. This is particularly useful for compatibility with tools like [tart-guest-agent](https://github.com/cirruslabs/tart-guest-agent) which expect specific console devices to be present.\r\n\r\nTo add console devices, use the `consoleDevices` field in your configuration:\r\n\r\n```yml\r\nconsoleDevices:\r\n  - tart-version-2\r\n```\r\n\r\n#### SSH Connect Retries\r\nAfter the VM starts, Cilicon connects to the guest over SSH to run any preRun/postRun commands and the provisioner. Some images may take a while before the SSH service is ready. Use `sshConnectMaxRetries` to control how many connection attempts Cilicon will make before giving up (default: 10).\r\n\r\nExample:\r\n\r\n```yml\r\nsshConnectMaxRetries: 20\r\n```\r\n\r\n### 🔨 Setting Up the Host OS\r\nIt is recommended to use Cilicon on a macOS device fully dedicated to the task, ideally one that is [freshly restored](https://support.apple.com/en-gb/guide/apple-configurator-mac/apdd5f3c75ad/mac).\r\n\r\nIf you don't want to host your machine locally, [OakHost](https://www.oakhost.net/) provides great value dedicated Macs and are kindly offering 10% off the first two months for new customers with the code `CILICON10` (Disclaimer: We do not receive any form of compensation from sharing this code).\r\n\r\n- Transfer `Cilicon.app`, `cilicon.yml` as well as any other files referenced by your config (e.g. Local image, GitHub private key etc.) to your Host OS.\r\n- Add `Cilicon.app` as a launch item\r\n- Set up Automatic Login\r\n- Disable automatic software updates\r\n- Disable any concept of screen lock, battery saving etc.\r\n\r\n\r\n## 🔮 Ideas for the Future\r\n\r\n### Support for more Provisioners\r\nWe use GitHub Actions for our iOS builds at [Trade Republic](https://traderepublic.com) but would love to see Cilicon being used for other CI services as well.\r\nImplementing support for more services should be easy by building on top of the `Provisioner` protocol.\r\n\r\n### Running 2 VMs in parallel\r\nXcode builds often don't use all of the compute resources available. Therefore running 2 VMs im parallel (more are not possible due to a limitation of the Virtualization framework) would be a welcome addition.\r\n\r\n### Monitoring\r\nA logging or monitoring concept would greatly improve identifying and troubleshooting any potential issues and provide the ability to notify the team in real time.\r\n\r\n## 👩‍💻 Join Us!\r\n\r\nAt [Trade Republic](https://traderepublic.com/), we are on a mission to democratize wealth. We set up millions of Europeans for wealth with fast, easy, and free access to capital markets. With over one million customers we are one of the largest savings platforms in Europe, with users holding over €6 billion on our platform. [Join us](https://traderepublic.com/careers?department=4026464003) to build the FinTech of the future.\r\n\r\n\r\n\r\n\u003e *Disclaimer*: Trade Republic is not affiliated with Cirrus Labs or their tart product\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftraderepublic%2Fcilicon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftraderepublic%2Fcilicon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftraderepublic%2Fcilicon/lists"}