Mac पर CircleCI self-hosted runner कैसे चलाएँ

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

• CircleCI में ऑर्गनाइज़ेशन एडमिन अधिकार। मेन्यू दिखने से पहले किसी एडमिन को Org, फिर Runners में रनर की शर्तें स्वीकार करनी होंगी।
• अकाउंट में कम से कम एक क्रेडिट। CircleCI कहता है कि रनर जॉब क्रेडिट इस्तेमाल नहीं करते, पर स्टोरेज और नेटवर्क ट्रांसफ़र कर सकते हैं।
• एडमिन एक्सेस, Homebrew और Xcode वाला Apple silicon Mac।
• sha256sum, जिसे CircleCI ज़रूरी चीज़ों में गिनता है। इसे brew install coreutils से पाएँ।

1. namespace और resource class बनाएँ

वेब ऐप में Runners खोलें और Create Resource Class चुनें। हर ऑर्गनाइज़ेशन को एक namespace मिलता है। अगर आप orbs पब्लिश करते हैं, तो यह आपके पास पहले से है। resource class का नाम कुछ ऐसा रखें, mac-mini-m6। Save करें और टोकन कॉपी करें। CircleCI इसे सिर्फ़ एक बार दिखाता है।

CLI भी यही करता है:

circleci namespace create <name> --org-id <your-organization-id>
circleci runner resource-class create <namespace>/<resource-class> <description> --generate-token

2. Homebrew से रनर इंस्टॉल करें

brew tap circleci-public/circleci
brew trust circleci-public/circleci
brew install circleci-runner

बीच की लाइन नई है। Homebrew 7.0.7, जो अक्टूबर 2026 में हमारे Mac पर था, थर्ड-पार्टी tap के पैकेज तब तक लोड नहीं करता, जब तक आप उस पर भरोसा न जताएँ। CircleCI के पेज पर यह स्टेप अभी नहीं है। रनर Homebrew cask के रूप में आता है।

macOS एक नोटिस दिखा सकता है कि Circle Internet Services का एक background item जोड़ा गया। यह सामान्य है। Homebrew LaunchAgent plist भी ~/Library/LaunchAgents/com.circleci.runner.plist में लिखता है।

3. config.yaml में टोकन डालें

nano $HOME/Library/Preferences/com.circleci.runner/config.yaml

runner:
  name: "mac-mini-m6"
  working_directory: "/Users/$USER/Library/com.circleci.runner/workdir"
  cleanup_working_directory: true
api:
  auth_token: "your-resource-class-token"

cleanup_working_directory चालू हो, तो हर जॉब साफ़ checkout से शुरू होता है। Xcode का DerivedData डिफ़ॉल्ट रूप से ~/Library/Developer/Xcode/DerivedData में रहता है, इसलिए बिल्ड कैश फिर भी बचे रहते हैं। अगर आप working directory के अंदर -derivedDataPath देते हैं, तो cleanup उसे हर जॉब के बाद मिटा देता है।

टोकन को सुरक्षित रखें

resource class टोकन से ही कोई मशीन उस class के जॉब ले पाती है। जो भी इसे पढ़ ले, वह अपनी मशीन जोड़कर आपके जॉब, आपके secrets के साथ, पा सकता है। config फ़ाइल को सिर्फ़ अपने यूज़र तक सीमित रखें। और अगर टोकन कभी लीक हो, तो उसे बदल दें।

chmod 600 $HOME/Library/Preferences/com.circleci.runner/config.yaml
ls -l $HOME/Library/Preferences/com.circleci.runner/config.yaml

यही बात जॉब पर भी लागू है। वे उस macOS यूज़र के रूप में चलते हैं, जिसने रनर शुरू किया, और बाकी सब के साथ एक ही डिस्क पर। इस resource class पर सिर्फ़ भरोसेमंद प्रोजेक्ट भेजें।

4. notarization स्वीकार करें

बाइनरी इंटरनेट से आती है, इसलिए macOS को इसे मंज़ूरी देनी होती है। CircleCI पहले signature जाँचने और फिर quarantine फ़्लैग हटाने का तरीका बताता है।

spctl -a -vvv -t install "$(brew --prefix)/bin/circleci-runner"
sudo xattr -r -d com.apple.quarantine "$(brew --prefix)/bin/circleci-runner"

पहले कमांड को accepted बताना चाहिए, source Notarized Developer ID के साथ।

5. रनर को GUI domain में शुरू करें

इन्हें Mac के डेस्कटॉप पर Terminal से चलाएँ। GUI domain लॉग-इन किया हुआ डेस्कटॉप सेशन है। Simulator और लॉग-इन keychain वहीं रहते हैं।

launchctl bootstrap gui/$(id -u) $HOME/Library/LaunchAgents/com.circleci.runner.plist
launchctl enable gui/$(id -u)/com.circleci.runner
launchctl kickstart -k gui/$(id -u)/com.circleci.runner
launchctl print gui/$(id -u)/com.circleci.runner

CircleCI headless सेशन के लिए user domain का विकल्प भी बताता है। यह plist को /Library/LaunchAgents में ले जाता है। macOS 27 पर हमने देखा कि उस फ़ोल्डर की plist हर बूट पर ऑटो-लॉग-इन तोड़ देती है। headless Mac पर ऑटो-लॉग-इन देखें। iOS काम के लिए हम ऑटोमैटिक लॉग-इन के साथ GUI domain सुझाते हैं।

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

~/Library/LaunchAgents में रखी plist तब लोड होती है, जब उसका यूज़र लॉग-इन करता है। System Settings में, Users and Groups के नीचे, इस अकाउंट के लिए ऑटोमैटिक लॉग-इन चालू करें। sudo pmset -a sleep 0 से स्लीप बंद करें। एक बार रीबूट करें और फिर से launchctl print जाँचें। लॉग ~/Library/Logs/com.circleci.runner/runner.log में हैं।

7. किसी जॉब को Mac पर भेजें

version: 2.1

jobs:
  ios-tests:
    machine: true
    resource_class: your-namespace/mac-mini-m6
    steps:
      - checkout
      - run:
          name: Run tests
          command: |
            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
      - run:
          name: Zip result bundle
          when: always
          command: ditto -c -k --keepParent build/TestResults.xcresult TestResults.xcresult.zip
      - store_artifacts:
          path: TestResults.xcresult.zip

workflows:
  ios:
    jobs:
      - ios-tests

CircleCI के डॉक्स दो फ़ील्ड बताते हैं, जो रनर जॉब में होने ही चाहिए: machine: true और resource_class। यहाँ कोई macos: xcode: key नहीं है, क्योंकि आप इमेज नहीं चुनते। जॉब वही Xcode इस्तेमाल करता है, जो Mac पर चुना हुआ है। MacRun Mac पर यह iOS 26.5 सिम्युलेटर रनटाइम के साथ Xcode 26.6 है।

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

• Refusing to load cask ... from untrusted tap। brew trust circleci-public/circleci चलाएँ, फिर दोबारा इंस्टॉल करें।
• macOS बाइनरी को ब्लॉक करता है। आपने notarization वाला स्टेप छोड़ दिया। ऊपर वाला xattr कमांड चलाएँ।
• जॉब कतार में हैं पर कभी शुरू नहीं होते। जाँचें कि config.yml का resource class आपके बनाए class से मेल खाता है, फिर runner.log पढ़ें।
• Docker layer caching काम नहीं करती। CircleCI इसे self-hosted रनर पर अनसपोर्टेड बताता है।
• xcodebuild: error: Existing file at -resultBundlePath। टेस्ट स्टेप से पहले पुराना bundle मिटाएँ। Xcode 26.6 पर हमें यह एरर मिला।

रनर रोकने के लिए launchctl bootout gui/$(id -u)/com.circleci.runner इस्तेमाल करें। इसे हटाने के लिए brew uninstall --cask circleci-public/homebrew-circleci/circleci-runner चलाएँ।

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

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

CircleCI का होस्टेड macOS कब काफ़ी है

CircleCI अपने Mac executor चलाता है। अक्टूबर 2026 में पढ़े गए उसके डॉक्स में 6 vCPU और 28 GB वाला m4pro.medium है, और 12 vCPU और 56 GB वाला m4pro.large। दोनों में हमारे 16 GB M6 से ज़्यादा मेमोरी है। अगर आपके टेस्ट सूट को इतनी मेमोरी चाहिए, या आप हफ़्ते में कुछ ही बार बिल्ड करते हैं, तो होस्टेड पर रहें। अगर आपको SLA, स्टैटिक IP या कई रीजन चाहिए, तो भी MacRun न लें।

सेटअप में MacRun की तरफ़ का हिस्सा दूसरे CI सिस्टम पर देखें, या अपने मिनटों के साथ खर्च की तुलना करें।