iOS बिल्ड के लिए Mac पर GitLab Runner कैसे सेट करें

पहले क्या चाहिए

• एडमिन एक्सेस और इंस्टॉल Xcode वाला Apple silicon Mac।
• Xcode का पहला लॉन्च पूरा हो। पक्का न हो, तो एक बार sudo xcodebuild -runFirstLaunch चलाएँ।
• अपने GitLab प्रोजेक्ट या ग्रुप में रनर मैनेज करने की अनुमति।
• Mac पर एक डेस्कटॉप सेशन, स्क्रीन शेयरिंग या मॉनिटर से। GitLab का macOS इंस्टॉल पेज लोकल GUI टर्मिनल इस्तेमाल करने को कहता है, SSH सेशन नहीं।
• वह macOS अकाउंट जो जॉब चलाएगा। डेस्कटॉप पर उसी यूज़र से साइन-इन करें।

1. रनर बाइनरी डाउनलोड करें

GitLab कहता है कि वह Homebrew formula मेंटेन नहीं करता, और आधिकारिक बाइनरी सुझाता है। Apple silicon पर arm64 बिल्ड इस्तेमाल करें। नए Mac पर शायद /usr/local/bin अभी न हो, इसलिए पहले उसे बनाएँ।

sudo mkdir -p /usr/local/bin
sudo curl --output /usr/local/bin/gitlab-runner \
  "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-arm64"
sudo chmod +x /usr/local/bin/gitlab-runner
gitlab-runner --version

2. GitLab में रनर बनाएँ

रनर रजिस्ट्रेशन टोकन अब deprecated हैं। GitLab इन्हें GitLab 20.0 में हटाने वाला है। मौजूदा तरीके में पहले UI में रनर बनता है, फिर आपको एक रनर ऑथेंटिकेशन टोकन मिलता है। वह टोकन glrt- से शुरू होता है।

• अपने प्रोजेक्ट में Settings खोलें, फिर CI/CD, फिर Runners को खोलें।
• Create project runner चुनें और macOS चुनें।
• Tags में macos, xcode डालें। Run untagged jobs को बंद रहने दें, ताकि यहाँ सिर्फ़ वही जॉब आएँ जो Mac माँगते हैं।
• Create runner चुनें और टोकन कॉपी करें। यह थोड़ी देर ही दिखता है।

टैग अब GitLab में रनर पर रहते हैं। GitLab के डॉक्स कहते हैं कि --tag-list और --run-untagged जैसी सेटिंग सिर्फ़ रनर बनाते समय, UI या API से, सेट हो सकती हैं। बाद में टैग रनर के Edit पेज से बदलें।

3. shell executor के साथ रजिस्टर करें

GitLab का macOS इंस्टॉल पेज iOS और macOS बिल्ड के लिए shell executor बताता है। जॉब सीधे Mac पर, आपके यूज़र के रूप में, Xcode और सिम्युलेटर के साथ चलते हैं। बिना प्रॉम्प्ट के ऐसे रजिस्टर करें:

export RUNNER_TOKEN="glrt-paste-your-token-here"
gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "shell" \
  --description "mac-mini-m6"

self-managed GitLab पर इसकी जगह अपने इंस्टेंस का URL डालें। सेटिंग ~/.gitlab-runner/config.toml में जाती हैं। GitLab बताता है कि shell executor मेंटेनेंस मोड में है। इसे अब भी सुरक्षा फ़िक्स मिलते हैं, और Xcode काम के लिए macOS पेज अब भी यही सुझाता है।

4. सर्विस इंस्टॉल करें और शुरू करें

cd ~
gitlab-runner install
gitlab-runner start
gitlab-runner status

इससे ~/Library/LaunchAgents/gitlab-runner.plist बनती है। macOS पर रनर एक यूज़र LaunchAgent है, और GitLab कहता है कि सिर्फ़ यही मोड सपोर्टेड है। यह आपके रूप में चलता है, root के रूप में नहीं। यह आपके keychain और लॉग-इन सेशन तक पहुँच सकता है, जो iOS Simulator और कोड साइनिंग को चाहिए। लॉग ~/Library/Logs/gitlab-runner.out.log और gitlab-runner.err.log में जाते हैं।

5. रीबूट के बाद भी चालू रखें

LaunchAgent तब शुरू होता है जब उसका यूज़र लॉग-इन करता है, और लॉगआउट पर रुक जाता है। इसलिए रीबूट के बाद रनर तभी लौटता है, जब वह यूज़र खुद लॉग-इन हो। इसी वजह से GitLab के डॉक्स ऑटोमैटिक लॉग-इन चालू करने को कहते हैं। इसे System Settings में, Users and Groups के नीचे करें। फिर Mac को स्लीप होने से रोकें और असली रीबूट से टेस्ट करें।

sudo pmset -a sleep 0
sudo shutdown -r now
# after it comes back, over SSH:
gitlab-runner status

headless ऑटो-लॉग-इन कुछ तरीकों से चुपचाप फ़ेल होता है, जिनमें एक macOS 27 में नया है। हमने इन्हें headless Mac पर ऑटो-लॉग-इन में लिखा है।

6. iOS ऐप के लिए .gitlab-ci.yml

जॉब किसी रनर पर तभी चलता है, जब रनर पर जॉब के सारे टैग हों। यह जॉब macos माँगता है, टेस्ट चलाता है, और टेस्ट फ़ेल होने पर भी result bundle रखता है।

stages:
  - test

ios_tests:
  stage: test
  tags:
    - macos
  script:
    - xcodebuild -version
    - rm -rf build/TestResults.xcresult
    - xcodebuild test -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.5' -resultBundlePath build/TestResults.xcresult
  artifacts:
    when: always
    paths:
      - build/TestResults.xcresult
    expire_in: 1 week

जो मशीन अपनी working copy रखती है, उस पर rm -rf वाली लाइन ज़रूरी है। xcodebuild मौजूदा result bundle के ऊपर लिखने से मना करता है। हमने इसे Xcode 26.6 पर जाँचा।

आम एरर और उनके हल

ये GitLab के macOS troubleshooting सेक्शन से हैं।

• "launchctl" failed: Could not find domain for। आपने install या start SSH से चलाया। Mac के डेस्कटॉप पर Terminal खोलें और वहाँ चलाएँ।
• FATAL: Failed to start gitlab-runner: exit status 134। सर्विस ठीक से इंस्टॉल नहीं है। डेस्कटॉप से gitlab-runner uninstall चलाएँ, फिर install, फिर start।
• Apple silicon पर killed: 9। plist में दिए लॉग फ़ोल्डर मौजूद होने चाहिए, और आपका यूज़र उनमें लिख सके।
• Failed to authorize rights (0x1) with status: -60007। DevToolsSecurity -enable और sudo security authorizationdb remove system.privilege.taskport is-developer चलाएँ।
• git fetch अटक जाता है। Homebrew वाला Git एक keychain credential helper जोड़ सकता है। रनर यूज़र के रूप में git config --global --add credential.helper '' चलाएँ।
• कोई जॉब अटका पड़ा है। उसके टैग रनर के टैग से मेल नहीं खाते। या जॉब पर कोई टैग नहीं है, और रनर बिना टैग वाले जॉब नहीं लेता।

डेडिकेटेड Mac क्यों मदद करता है

shell executor हर जॉब के लिए वही मशीन इस्तेमाल करता है। Xcode का DerivedData, Swift पैकेज checkouts और CocoaPods कैश पाइपलाइन के बीच डिस्क पर रहते हैं। समय वहीं जाता है। Xcode 26.6 पर Wikipedia iOS ऐप वाले हमारे बेंचमार्क में हमने छोटे बदलाव के बाद एक आम जॉब का समय मापा। वॉर्म M6 पर इसमें 27 सेकंड लगे। नए GitHub-होस्टेड macos-26 रनर पर वही जॉब 269 सेकंड का था। क्लीन बिल्ड 86 सेकंड का था, सामने 183।

GitLab के होस्टेड Mac रनर कब काफ़ी हैं

GitLab अपने macOS रनर चलाता है। अक्टूबर 2026 में पढ़े गए उसके डॉक्स इन्हें beta बताते हैं। ये Premium और Ultimate ग्राहकों और ओपन सोर्स प्रोग्राम के लिए हैं। साइज़ हैं: 4 vCPU और 8 GB वाला M1, और 6 vCPU और 16 GB वाला M2 Pro। अगर आप इनमें से किसी प्लान पर हैं और दिन में कुछ पाइपलाइन चलाते हैं, तो होस्टेड रनर आपको ऊपर के सारे स्टेप से बचा देते हैं।

ऐसे पब्लिक प्रोजेक्ट के लिए shell executor वाला डेडिकेटेड Mac न चुनें, जो अनजान merge request चलाता है। GitLab चेतावनी देता है कि shell जॉब उसी मशीन पर दूसरे प्रोजेक्ट का कोड पढ़ सकते हैं। अगर आपको allowlisting के लिए स्टैटिक IP, SLA, या एक से ज़्यादा रीजन चाहिए, तो भी MacRun न लें। हम इनमें से कुछ नहीं देते।

हमारे हार्डवेयर पर आज़माना चाहते हैं? हमारा दूसरे CI सिस्टम वाला पेज MacRun की तरफ़ का सेटअप बताता है, और प्राइसिंग पर हर टियर है।