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 or on a specified repository. 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 or account. This can be done by under "Developer settings" in your organization's or your personal settings or by following this link when creating the GitHub app on a personal account or the following link when creating the GitHub app on an organization: https://github.com/organizations/{YOUR_ORGANIZATION_NAME}/settings/apps. Remember to change the link to include the name of your organization if needed.
2. When creating the GitHub App, the required permissions depend on whether you are creating the app for an organization or a personal account. Organizations should enable the Organization: Self-hosted runners (Read and write) permission and personal accounts should enable both the Repository: Administration (Read and Write) and Repository: Metadata (Read-only) permissions.
3. Install the GitHub app on your organization.
4. Select "Generate a private key". Tartelet will use this to send authorized requests to the API. The generated key should automatically be downloaded.
5. 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.
6. Launch Tartelet, open its settings, and select the GitHub pane.
7. Select the Runner Scope that is relevant to you. Select "Organization" for organizations and "Repository" for personal accounts that wish to install runners on a specific repository.
8. Fill in either your organization name or the name of your account and the repository you wish to install the runners on.
9. Fill in the app ID. This can be found under the GitHub app that you just created.
10. Select the private key file. The file is stored securely in the keychain of the host machine.
11. 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 should specify the following:

• The name of the virtual machine.
• The size of the disk associated with the virtual machine using the --disk-size flag. Make sure this is big enough for the software you want to install.
• The IPSW containing the operating system to install on the virtual machine using the --ipsw-file 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 and a disk of 80 GB.

tart create runner --disk-size=120 --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. Select the virtual machine in Tartelet

Follow the steps below to configure Tartelet to use the newly created virtual machine.

1. Launch Tartelet.
2. Open the settings and select the Virtual Machine pane.
3. Select your newly created virtual machine in the dropdown.

You may also select the number of virtual machines you want Tartelet to run. By default Tartelet will run a single virtual machine, meaning that your host machine can only facilitate one GitHub Actions job at a time. You can increase this to two virtual machines to handle two jobs in parallel.

ℹ️ Note

In theory Tartelet could handle any number of virtual machines but Apple's Virtualization framework limits developers to run at maximum virtual machines at once.

3. Edit the virtual machine

Editing a virtual machine means booting virtual machine selected in Tartelet's settings and making changes to it, such as installing new software on the machine. We will edit the virtual machine to prepare it to run a GitHub Actions runner.

To edit the virtual machine, select "Virtual Machine" and then "Edit Virtual Machine" in Tartelet's menu bar. The following steps will guide you through editing the virtual machine.

4. Complete the macOS setup

The first time the virtual machine is booted, you must complete setup of macOS. 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

ℹ️ Note

If you have followed the Setting Up a Host Machine article you will realize that we are now juggling two accounts named runner:

• The account that has Tartelet installed on the host machine.
• The account on the virtual machine.

This can be confusing at first but we have found these account names to make sense for us at Shape.

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

4. Enable automatically logging in

It is key that the runner used is automatically logged in when booting the virtual machine. Otherwise the ephemeral virtual machines would not be able to start the GitHub Actions runner. Follow the steps below to enable automatically logging in.

1. Navigate to the "Users & Groups" pane in the System Settings app.
2. Select the runner account next to the "Automatically log in as" setting.
3. Enter the passwords when prompted to.

5. Disable automatic updates

The virtual machine should not automatically install as jobs should always run in the same environment and we do not want it to spend resources downloading updates. Therefore we disable both.

1. Navigate to the General pane in the System Settings app.
2. Select "Software Update".
3. Select the info icon next to the "Automatic updates" setting.
4. Disable all toggles.

The settings should look as in the screenshot below.

6. Disable Screen Saver and turning off the display

It is unnecessary for the virtual machine to start the screen saver or turn off the display so we disable it.

1. Navigate to the "Lock Screen" pane in the System Settings app.
2. Select "Never" for the "Start Screen Saver when inactive" setting.
3. Select "Never" for the "Turn off display when inactive" setting.
4. Select "Never" for the "Require password after the screen saver begins or display is turned off" setting.

The settings should look as shown in the screenshot below.

7. Disable showing suggested and recent apps in the Dock

1. Navigate to the Desktop & Dock pane in the System Settings app
2. Disable the "Show suggested and recent apps in Dock" setting.

8. Disable clicking wallpaper to reveal desktop

1. Navigate to the Desktop & Dock pane in the System Settings app
2. Set the "Click wallpaper to reveal desktop" setting to "Only in Stage Manager".

9. Enable passwordless sudo

Jobs performed by the runner will likely need to run actions as sudo. Since jobs are running in an ephemeral virtual machine, it is safe to enable passwordless sudo. Furthermore, this aligns with the behavior of GitHub's runners.

1. Open the Terminal app.
2. Run the command sudo visudo and enter the password when asked to.
3. Find this line in the file: %admin ALL = (ALL) ALL
4. Change the line to this: %admin ALL = (ALL) NOPASSWD: ALL
5. Save the file and quit the editor.

10. Enable Remote Login

We will enable Remote Login to allow the host machine to SSH into the virtual machine through Tartelet to set up and start the GitHub Actions runner.

1. Navigate to the "General" pane in the System Settings app.
2. Select "Sharing".
3. Enable" "Remote Login".

11. Shutdown the virtual machine

The virtual machine is now configured and we can shut it down.

1. Close all running apps and windows.
2. Select the Apple logo in the menu bar.
3. Select "Shut Down" from the menu.

12. Add SSH credentials to Tartelet

Finally, we will add the credentials of the runner account to Tartelet so that it can SSH into the virtual machine to configure and start the GitHub Actions runner.

1. Navigate to the "Virtual Machine" pane in Tartelet's settings.
2. Scroll down to the SSH section.
3. Enter the username and password of the virtual machine's macOS account.

If you have followed this guide meticulously, you should enter the following username and password.

Field	Value
Username	runner
Password	runner

Next Steps

Tartelet is now ready to manage a fleet of ephemeral virtual machines. If you are planning to use the runners to run build iOS apps, you may have a look at the Configuring the Virtual Machine to Build iOS Apps article which describes the software we have installed on the machine at Shape and configurations we have made to build our iOS apps.

Otherwise you should have a look at the Starting the Virtual Machines article to start the virtual machines.