Configuring Tartelet

After installing Tartelet it must be configured with the virtual machine to run and the credentials needed to register the runners on GitHub.

Adding the GitHub Credentials

Tartelet will automatically register the virtual machine as a runner on a GitHub organization. In order to do this it must be configured with the relevant credentials. Follow the steps below to add the credentials to Tartelet.

ℹ️ Note

If you have already created a GitHub App and you are setting up another host machine, you can reuse the credentials from the existing GitHub App. The credentials do not need to be different for each host machine.

1. Create a GitHub App on your organization. This can be done by under "Developer settings" in your organization's settings or by following this link: https://github.com/organizations/{YOUR_ORGANIZATION_NAME}/settings/apps. Remember to change the link to include the name of your organization.
2. When creating the GitHub App, make sure to give it read/write permissions to the self-hosted runners and to disable the webhook.
3. Select "Generate a private key". Tartelet will use this to send authorized requests to the API. The generated key should automatically be downloaded.
4. Transfer the generated private key to your host machine. If you are using VNC, the private key can be dragged on top of the VNC window to transfer it.
5. Launch Tartelet, open its settings, and select the GitHub pane.
6. Fill out the name of your organization.
7. Fill out the app ID. This can be found under the GitHub app that you just created.
8. Select the private key file. The file is stored securely in the keychain of the host machine.
9. Make sure to delete the transferred private key from the host machine.

When everything is configured correctly, the settings should look similar to the screenshot below.

Creating a Virtual Machine

Tartelet builds upon Tart which it uses to manage the ephemeral virtual machines, that is, Tartelet uses Tart to clone, run, and delete virtual machines.

This section guides you through creating and configuring a virtual machine using Tart and configuring Tartelet to use that virtual machine for the GitHub Actions runners. All steps should be performed on your host machine.

ℹ️ Note

If you are configuring another host machine and have previously created a virtual machine, you can transfer that virtual machine to your new host machine. Please refer to the Copying a Virtual Machine article for the details on reusing an existing virtual machine on the host machine.

1. Create a virtual machine

Uses the tart CLI's create command to create a virtual machine. When creating a virtual machine, you must specify the name of the virtual machine to create and a link to the IPSW file containing the operating system to install on the virtual machine. You do this by passing the link using the --from-ipsw flag. You can find links to IPSW files on ipsw.me.

For example, run the following command to create a virtual machine named runner with macOS 13.2.1.

tart create runner --from-ipsw=https://updates.cdn-apple.com/2023WinterFCS/fullrestores/032-48346/EFF99C1E-C408-4E7A-A448-12E1468AF06C/UniversalMac_13.2.1_22D68_Restore.ipsw

This will take a couple of minutes since IPSW files are around 12.5 GB and that needs to be downloaded.

2. Run the virtual machine

Use the tart CLI's run command to run the virtual machine. When running the virtual machine you must specify the name of the virtual machine.

tart run runner

3. Complete the macOS setup

You must complete setup of macOS in your virtual machine. This virtual machine will be used to run your GitHub Actions runner, and as such, you should configure the environment to match your needs. The table below list the configuration we use at Shape.

Setup Step	Setting
Language	English
Country or Region	Denmark
Written and Spoken Languages	Left with the recommended settings
Accessibility	No settings chosen
Migration Assistant	No migration performed
Sign in with your Apple ID	Skipped

When asked to create an account on the computer, we recommend creating the account with the following information. The account name is carefully chosen to match the account name used on GitHub's runners in case any third-party actions rely on this.

Field	Value
Full name	runner
Account name	runner. Matches the account name used on GitHub's runners.
Password	runner. The ephemeral virtual machines do not require a secure password.
Hint	None

In the following steps we use the settings below at Shape.

Setup Step	Setting
Location Services	Skip to leave disabled
Time Zone	Copenhagen - Denmark
Analytics	Disable sharing analytics with Apple
Screen Time	Do not set up
Siri	Do not enable Siri
Look	Light