Getting Started

The GetMac GitLab Executor is a custom GitLab Runner executor that enables your CI/CD jobs to run on ephemeral GetMac macOS virtual machines. Each job gets a fresh macOS VM that is automatically created before the job and deleted after it completes.

Prerequisites

Active GetMac account (free tier available)
GetMac API key from the dashboard
GitLab Runner installed on your machine

Step 1: Install GitLab Runner

Install GitLab Runner on the machine that will orchestrate your CI/CD jobs. Follow the official GitLab Runner installation guide for your operating system.

Step 2: Register Runner

Step 3: Configure config.toml

Add the following to the [runners.custom] section in your GitLab Runner's config.toml:

[runners.custom]
config_exec = "getmac-gitlab-executor"
config_args = ["config", "--getmac-cloud-api-key", "<API_KEY>"]
prepare_exec = "getmac-gitlab-executor"
prepare_args = ["prepare"]
run_exec = "getmac-gitlab-executor"
run_args = ["run"]
cleanup_exec = "getmac-gitlab-executor"
cleanup_args = ["cleanup"]

Step 4: Set Environment Variables

Configure the following environment variables for the executor:

Variable	Required	Default	Description
`GETMAC_CLOUD_API_KEY`	Yes	—	Your GetMac API key
`GETMAC_CLOUD_PROJECT_ID`	Yes	—	Your GetMac project ID
`GETMAC_CLOUD_API_URL`	Yes	`https://api.getmac.io/v1`	GetMac API endpoint
`GETMAC_CLOUD_MACHINE_IMAGE`	No	`macos-sequoia`	VM operating system image
`GETMAC_CLOUD_MACHINE_TYPE`	No	`mac-m4-c4-m8`	Hardware specification
`GETMAC_CLOUD_REGION`	No	`eu-central-ltu-1`	Geographic region
`GETMAC_CLOUD_SSH_PRIVATE_KEY_PATH`	No	`$HOME/.ssh/id_rsa`	Path to SSH private key
`GETMAC_CLOUD_DEBUG`	No	—	Enable debug logging

See Configuration for full details on all options.

Step 5: Configure .gitlab-ci.yml

Add the following to your .gitlab-ci.yml to run jobs on GetMac runners:

variables:
  GETMAC_CLOUD_PROJECT_ID: "your-project-id"

stages:
  - build

build-job:
  stage: build
  tags:
    - getmac
  script:
    - echo "Building the project..."