Перейти к содержимому

GitLab CI/CD Runner на Mac Mini M4: полное руководство

Установите и настройте GitLab CI/CD runner на выделенном Mac Mini M4. Собирайте iOS-приложения нативно на Apple Silicon, запускайте тесты на реальных симуляторах и деплойте в TestFlight, всё из вашего пайплайна GitLab.

CI/CD 30 мин чтения Обновлено в ноябре 2026

Зачем использовать собственные GitLab Runner на Mac?

GitLab предлагает общие runner на Linux, но для сборки iOS-приложений требуется macOS, работающая на оборудовании Apple. Собственные macOS runner от GitLab ограничены и дороги. Собственный GitLab Runner на Mac Mini M4 даёт вам:

  • Неограниченные минуты CI/CD

    Бесплатный тариф GitLab включает 400 минут CI/CD на общих runner. На собственном runner ограничений нет.

  • Нативный Apple Silicon

    Собирайте на том же чипе M4, на котором работают устройства ваших пользователей. Никаких накладных расходов на трансляцию через Rosetta.

  • Полный контроль окружения

    Устанавливайте любую версию Xcode, симуляторы, инструменты и зависимости, которые вам нужны.

  • Постоянные кэши

    DerivedData, пакеты SPM и кэши CocoaPods сохраняются между запусками пайплайна.

Установка GitLab Runner

Подключитесь по SSH к вашему выделенному серверу сборки Mac mini M4 и установите GitLab Runner, а также xcbeautify для читаемых логов сборки, с помощью Homebrew:

# Connect to your Mac Mini M4
ssh admin@your-server-ip

# Put the preinstalled Homebrew on your PATH (once per account)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Install GitLab Runner with Homebrew, plus xcbeautify for the pipeline's build logs
brew install gitlab-runner xcbeautify

# Verify installation (prints the version and OS/Arch: darwin/arm64)
gitlab-runner --version

Установка как службы macOS

# Run the runner as a launchd service. It is a LaunchAgent: it starts when
# your user session starts, so on a headless Mac enable automatic login for
# this user (System Settings > Users & Groups) to bring it back after a reboot
brew services start gitlab-runner

# Verify the service is running
brew services list | grep gitlab-runner
# gitlab-runner started admin ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner.plist

Регистрация Runner

Откройте ваш проект в GitLab, перейдите в Settings > CI/CD > Runners и выберите Create project runner (для группы: Build > Runners > Create group runner). В поле Tags укажите macos и m4 (их использует пайплайн ниже), создайте runner и скопируйте его токен аутентификации, который начинается с glrt-. С токеном аутентификации команда register не принимает теги и другие параметры runner: они задаются здесь, в GitLab. Чтобы автоматизировать этот шаг, создайте runner через API (пример ниже).

Регистрация с токеном аутентификации runner

# Optional: create the runner with the API instead of the GitLab UI.
# Needs an access token with the create_runner scope; the "token"
# field of the response is the runner authentication token (glrt-...)
curl --request POST \
  --header "PRIVATE-TOKEN: YOUR_ACCESS_TOKEN" \
  --url "https://gitlab.com/api/v4/user/runners" \
  --data "runner_type=project_type" \
  --data "project_id=YOUR_PROJECT_ID" \
  --data "tag_list=macos,m4" \
  --data "run_untagged=false"

# Register the runner with its authentication token (starts with glrt-).
# Tags, untagged jobs and locking come from the runner you created in GitLab:
# do not pass --tag-list or --run-untagged with an authentication token
gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "YOUR_RUNNER_AUTHENTICATION_TOKEN" \
  --executor "shell" \
  --name "mac-mini-m4-runner"

# Confirm the runner can reach GitLab
gitlab-runner verify

Старый способ: регистрация с регистрационным токеном

Регистрационные токены объявлены устаревшими в GitLab 15.6, и GitLab планирует удалить их в GitLab 20.0. Начиная с GitLab 17.0 они работают, только если администратор (или, на GitLab.com, владелец группы верхнего уровня) снова их включил. Используйте этот способ только на экземпляре GitLab, который всё ещё этого требует.

# Legacy: registration token (deprecated since GitLab 15.6,
# removal scheduled for GitLab 20.0). On GitLab 17.0 and later,
# it works only where registration tokens were enabled again.
gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --registration-token "YOUR_REGISTRATION_TOKEN" \
  --executor "shell" \
  --description "mac-mini-m4-runner" \
  --tag-list "macos,apple-silicon,m4,ios,xcode" \
  --run-untagged="false"

Проверка конфигурации Runner

# View the runner config file
cat ~/.gitlab-runner/config.toml

# Expected output:
# concurrent = 2
# check_interval = 0
#
# [session_server]
#   session_timeout = 1800
#
# [[runners]]
#   name = "mac-mini-m4-runner"
#   url = "https://gitlab.com/"
#   token = "..."
#   executor = "shell"
#   [runners.cache]
#     MaxUploadedArchiveSize = 0

# Adjust concurrency based on your hardware:
# Mac Mini M4 (16GB): concurrent = 2
# Mac Mini M4 Pro (24GB): concurrent = 3
# Mac Mini M4 Pro (48GB): concurrent = 4

Отредактируйте ~/.gitlab-runner/config.toml, чтобы настроить параллелизм:

# Edit the config
nano ~/.gitlab-runner/config.toml

# Set concurrent to match your hardware capacity
concurrent = 2

# Restart the service to apply changes
brew services restart gitlab-runner

Runner должен теперь отображаться как Online в вашем проекте GitLab в разделе Settings > CI/CD > Runners.

Создание .gitlab-ci.yml для iOS

Создайте файл .gitlab-ci.yml в корне вашего репозитория. Этот полный пайплайн собирает, тестирует и деплоит ваше iOS-приложение:

# .gitlab-ci.yml

stages:
  - build
  - test
  - deploy

variables:
  SCHEME: "MyApp"
  WORKSPACE: "MyApp.xcworkspace"
  # Any device listed by: xcrun simctl list devices available
  DESTINATION: "platform=iOS Simulator,name=iPhone 17,OS=latest"
  # Pick the Xcode for every job without sudo
  # (preinstalled Xcode; for another version, use the path from xcodes installed)
  DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"

# Only run on our Mac runner
default:
  tags:
    - macos
    - m4
  before_script:
    # The runner cleans the checkout (git clean -ffdx) before each job, so keep
    # DerivedData outside it: one warm folder per project and concurrent job slot
    - export DERIVED_DATA="${CI_BUILDS_DIR}/DerivedData/${CI_PROJECT_PATH_SLUG}-${CI_CONCURRENT_PROJECT_ID}"
    - xcodebuild -version
    # Pods/ is removed with the rest of the checkout's untracked files: reinstall it
    - |
      if [ -f "Podfile" ]; then
        pod install
      fi

# ---- BUILD ----

build:
  stage: build
  script:
    - |
      xcodebuild build \
        -workspace "${WORKSPACE}" \
        -scheme "${SCHEME}" \
        -destination "${DESTINATION}" \
        -derivedDataPath "${DERIVED_DATA}" \
        CODE_SIGNING_ALLOWED=NO \
        | xcbeautify

# ---- TEST ----

unit_tests:
  stage: test
  needs: ["build"]
  script:
    - |
      xcodebuild test \
        -workspace "${WORKSPACE}" \
        -scheme "${SCHEME}" \
        -destination "${DESTINATION}" \
        -derivedDataPath "${DERIVED_DATA}" \
        -resultBundlePath "TestResults.xcresult" \
        -parallel-testing-enabled YES \
        | xcbeautify --report junit --report-path build/reports
  artifacts:
    when: always
    paths:
      - TestResults.xcresult/
    reports:
      junit: build/reports/junit.xml
    expire_in: 7 days
  after_script:
    - xcrun simctl shutdown all 2>/dev/null || true

# ---- DEPLOY ----

deploy_testflight:
  stage: deploy
  needs: ["unit_tests"]
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - |
      # Install or update Fastlane
      which fastlane || brew install fastlane

      # Run Fastlane beta lane
      fastlane beta
  environment:
    name: testflight
  variables:
    MATCH_PASSWORD: ${MATCH_PASSWORD}
    # Names read by fastlane's app_store_connect_api_key action (call it in your lane)
    APP_STORE_CONNECT_API_KEY_KEY_ID: ${APP_STORE_KEY_ID}
    APP_STORE_CONNECT_API_KEY_ISSUER_ID: ${APP_STORE_ISSUER_ID}
    APP_STORE_CONNECT_API_KEY_KEY: ${APP_STORE_KEY_CONTENT}

Добавление переменных CI/CD в GitLab

Перейдите в Settings > CI/CD > Variables в вашем проекте GitLab и добавьте эти переменные как «Masked» и «Protected»:

  • MATCH_PASSWORD: пароль для шифрования Fastlane Match
  • APP_STORE_KEY_ID: ID ключа App Store Connect API
  • APP_STORE_ISSUER_ID: Issuer ID App Store Connect
  • APP_STORE_KEY_CONTENT: содержимое файла ключа .p8

Оптимизация производительности

Конфигурация кэша GitLab

На постоянном Mac самый быстрый кэш тот, который GitLab не нужно перемещать: пайплайн выше хранит DerivedData вне рабочей копии, поэтому он остаётся «тёплым» между задачами. С shell executor собственный кэш GitLab упаковывается и распаковывается в каждой задаче, поэтому используйте его для небольших папок, например Pods/:

# DerivedData already stays on disk outside the checkout (DERIVED_DATA above).
# Use GitLab's cache for small folders, keyed on the lockfile:
build:
  cache:
    key:
      files:
        - Podfile.lock
    paths:
      - Pods/
    policy: pull-push

# For test jobs that don't modify the cache, use pull-only:
unit_tests:
  cache:
    key:
      files:
        - Podfile.lock
    paths:
      - Pods/
    policy: pull

Использование артефактов для передачи данных между этапами

# Useful when the build and test jobs can run on different Macs.
# build-for-testing compiles the app and its test bundles once; artifacts must
# sit inside the project folder, so this job builds there
build:
  script:
    - |
      xcodebuild build-for-testing \
        -workspace "${WORKSPACE}" \
        -scheme "${SCHEME}" \
        -destination "${DESTINATION}" \
        -derivedDataPath build/DerivedData \
        | xcbeautify
  artifacts:
    paths:
      - build/DerivedData/Build/Products/
    expire_in: 2 hours

# The test stage receives the built products and runs them without rebuilding
unit_tests:
  needs: ["build"]  # downloads the build job's artifacts
  script:
    - |
      xcodebuild test-without-building \
        -xctestrun build/DerivedData/Build/Products/*.xctestrun \
        -destination "${DESTINATION}" \
        | xcbeautify

Параллельное выполнение тестов

# On one Mac, let xcodebuild split the test classes across simulator clones.
# (GitLab's parallel: keyword only helps if each copy runs a different part of
# the suite, using CI_NODE_INDEX and CI_NODE_TOTAL; otherwise it repeats it.)
unit_tests:
  stage: test
  script:
    - |
      xcodebuild test \
        -workspace "${WORKSPACE}" \
        -scheme "${SCHEME}" \
        -destination "${DESTINATION}" \
        -derivedDataPath "${DERIVED_DATA}" \
        -parallel-testing-enabled YES \
        -maximum-parallel-testing-workers 4 \
        | xcbeautify

Плановая очистка кэша

# On the Mac Mini, set up a weekly cleanup cron job
crontab -e

# Add these lines:
# Every Sunday at 3 AM, remove DerivedData folders not used for 7 days
# (the pipeline keeps them in ~/builds/DerivedData, one per project and slot)
0 3 * * 0 find ~/builds/DerivedData -mindepth 1 -maxdepth 1 -type d -mtime +7 -exec rm -rf {} + 2>/dev/null

# Checkouts in ~/builds are reused by the next job (git fetch): no need to delete them

# Clean Homebrew cache monthly
0 5 1 * * /opt/homebrew/bin/brew cleanup --prune=30 2>/dev/null

Устранение неполадок

Runner отображается как «offline» в GitLab

Runner работает как LaunchAgent, поэтому запускается при входе пользователя в систему: после перезагрузки он остаётся офлайн, пока этот пользователь не войдёт. На headless Mac включите автоматический вход для этого пользователя (Системные настройки > Пользователи и группы; недоступно, пока включён FileVault). Затем проверьте статус службы runner и логи:

# Check service status
brew services list | grep gitlab-runner

# View logs
cat /opt/homebrew/var/log/gitlab-runner.log

# Restart the service
brew services restart gitlab-runner

# Verify connectivity to GitLab
gitlab-runner verify

Ошибки отказа в доступе при сборке

Runner может нуждаться в доступе к директории разработчика Xcode:

# Ensure the runner user has Xcode access (run once, in your SSH session)
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

# If using simulators, ensure the user can access them
xcrun simctl list devices

Кэш не восстанавливается

Убедитесь, что ключи кэша согласованы и пути существуют:

# Check cache directory permissions
ls -la ~/builds/

# The shell executor stores caches locally by default
# Verify the cache directory in config.toml:
cat ~/.gitlab-runner/config.toml

# Ensure [runners.cache] section has the right settings
# For local caching (most efficient for persistent runners):
# [runners.cache]
#   Type = ""  # empty = local cache

Сборка Xcode зависает или превышает тайм-аут

Это часто вызвано запросами доступа к связке ключей или проблемами с симулятором:

# Unlock the keychain before builds
security unlock-keychain -p "YOUR_PASSWORD" ~/Library/Keychains/login.keychain-db

# Kill stuck simulators
xcrun simctl shutdown all
killall -9 com.apple.CoreSimulator.CoreSimulatorService 2>/dev/null || true

# Set a build timeout in .gitlab-ci.yml
build:
  timeout: 30 minutes

FAQ

Можно ли использовать Docker executor на macOS?
Docker на macOS запускает контейнеры Linux в виртуальной машине, которая не имеет доступа к API macOS, Xcode или симуляторам iOS. Для сборки iOS необходимо использовать shell executor. Docker подходит для серверного Swift или других задач на базе Linux, работающих параллельно с вашим Mac runner.
Как зарегистрировать runner для группы GitLab?
Откройте вашу группу в GitLab, перейдите в Build > Runners и выберите Create group runner (нужна роль Owner в группе). Зарегистрируйте Mac с токеном аутентификации этого группового runner. После этого runner будет доступен всем проектам группы.
Что лучше использовать: shell executor или SSH executor?
Используйте shell executor. Он выполняет команды непосредственно на Mac, что обеспечивает полный доступ к Xcode, симуляторам и связке ключей. SSH executor предназначен для удалённых машин, что не нужно, когда runner уже находится на Mac.
Можно ли запускать runner GitLab и GitHub Actions на одном Mac?
Да. Оба runner легковесны и могут работать одновременно на одном Mac Mini M4. Просто учитывайте общее потребление ресурсов при настройке уровня параллелизма для каждого runner.
Как обновить GitLab Runner?
# Update via Homebrew
brew upgrade gitlab-runner

# Restart the service
brew services restart gitlab-runner

# Verify the new version
gitlab-runner --version
Ищете полностью управляемый GitLab Runner? Попробуйте Cloud-Runner Пропустите настройку. Cloud-Runner предоставляет выделенные, предварительно настроенные GitLab Runner на оборудовании Mac, без установки и обслуживания.

Готовы ускорить ваши пайплайны GitLab?

Получите выделенный Mac Mini M4 для вашего GitLab CI/CD runner. Неограниченные сборки от $85/мес.

Цены My Remote Mac указаны в USD, без налогов.

Нужно больше деталей?

Полная документация: пошаговые инструкции по настройке, справочники по конфигурации и решение проблем.

Открыть документацию →