Mac पर Buildkite agent कैसे चलाएँ

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

• एक Buildkite cluster, और उसके एजेंट टोकन और queues मैनेज करने की अनुमति। आपको org admin या cluster maintainer होना चाहिए।
• macOS 11 या नए वर्ज़न वाला Mac। Buildkite यही न्यूनतम बताता है। साथ में Apple silicon, Homebrew, Xcode और एडमिन एक्सेस।
• एक SSH key, जिससे एजेंट आपकी रिपॉज़िटरी clone कर सके।

1. एक queue और एक एजेंट टोकन बनाएँ

Buildkite में Agents चुनकर Clusters पेज पर जाएँ और अपना cluster चुनें। Queues पेज पर New Queue चुनें। इसे key macos दें और Self hosted चुनें। फिर Agent Tokens खोलें, New Token चुनें, विवरण जोड़ें और इसे बनाएँ। वैल्यू कॉपी करें। Buildkite इसे एक ही बार दिखाता है।

टोकन फ़ॉर्म में Allowed IP Addresses फ़ील्ड है। MacRun पर इसे खाली छोड़ें। हमारे Mac के पास कोई स्टैटिक पब्लिक IP नहीं है, इसलिए CIDR नियम एजेंट को बाहर कर देगा।

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

brew tap buildkite/buildkite
brew trust buildkite/buildkite
brew install buildkite/buildkite/buildkite-agent

Homebrew 7.0.7, जो अक्टूबर 2026 में हमारे Mac पर था, थर्ड-पार्टी tap के formulas तब तक नहीं लेता, जब तक आप उस पर भरोसा न जताएँ। बीच वाली लाइन यही करती है। formula का नाम अब buildkite-agent@3 है, और Buildkite के डॉक्स वाला पुराना नाम अब भी उसी की ओर जाता है।

Apple silicon पर फ़ाइलें /opt/homebrew के नीचे आती हैं:

• Config: /opt/homebrew/etc/buildkite-agent/buildkite-agent.cfg
• Hooks: /opt/homebrew/etc/buildkite-agent/hooks
• Log: /opt/homebrew/var/log/buildkite-agent.log

अपनी मशीन पर सटीक पाथ देखने के लिए brew info buildkite-agent चलाएँ।

3. टोकन और queue टैग जोड़ें

Buildkite के डॉक्स placeholder टोकन बदलने के लिए sed इस्तेमाल करते हैं। बड़े अक्षरों वाले टेक्स्ट की जगह अपना टोकन डालें।

sed -i '' "s/xxx/INSERT-YOUR-AGENT-TOKEN-HERE/g" "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg
cat "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg | grep token

फिर वही फ़ाइल खोलें और tags वाली लाइन सेट करें, ताकि एजेंट आपकी queue में जुड़ जाए:

tags="queue=macos"

एक एजेंट cluster की एक self-hosted queue का हिस्सा होता है। queue टैग न हो, तो यह default queue में जुड़ता है। अगर cluster में कोई default self-hosted queue नहीं है, तो Buildkite कहता है कि एजेंट कनेक्ट नहीं हो पाता।

4. इसे टेस्ट करें, फिर सर्विस के रूप में चलाएँ

इसे एक बार foreground में शुरू करें। यह cluster की एजेंट लिस्ट में दिखना चाहिए।

buildkite-agent start

इसे Control C से रोकें। Homebrew formula के साथ एक सर्विस परिभाषा आती है। यह ऊपर वाली config के साथ buildkite-agent start चलाती है, फ़ेल होने पर फिर शुरू करती है, और उसी फ़ाइल में लॉग लिखती है। इसे Mac के डेस्कटॉप पर Terminal से शुरू करें:

brew services start buildkite/buildkite/buildkite-agent@3
brew services list | grep buildkite

macOS पर एजेंट उस यूज़र के रूप में चलता है, जिसने launchd सर्विस शुरू की। इसे उस अकाउंट से शुरू करें, जिसके पास Xcode और आपकी साइनिंग keys हैं।

हर Mac पर एक एजेंट से शुरू करें। Buildkite config फ़ाइल में spawn सेटिंग और --spawn फ़्लैग बताता है, जिससे एक सर्विस से कई एजेंट चलते हैं। एक साथ दो Xcode बिल्ड उन्हीं कोर और मेमोरी के लिए लड़ते हैं। 16 GB मशीन पर पहले एक एजेंट को मापें, फिर दो आज़माएँ।

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

formula के अपने इंस्टॉल नोट्स कहते हैं कि Mac को इस यूज़र के रूप में अपने आप लॉग-इन होने के लिए सेट करें। Buildkite के tap का README यह सौदा समझाता है। LaunchAgent को लॉग-इन चाहिए, पर इससे टेस्ट iOS Simulator जैसे GUI टूल इस्तेमाल कर पाते हैं। System Settings में, Users and Groups के नीचे, ऑटोमैटिक लॉग-इन चालू करें। फिर स्लीप बंद करें, रीबूट करें, और एजेंट लिस्ट देखें।

sudo pmset -a sleep 0
sudo shutdown -r now

plist को अपने होम फ़ोल्डर के LaunchAgents में रखें, जहाँ Homebrew उसे रखता है। macOS 27 पर हमने देखा कि /Library/LaunchAgents में रखी plist ऑटो-लॉग-इन तोड़ देती है। headless Mac पर ऑटो-लॉग-इन देखें।

6. Mac के लिए एक पाइपलाइन स्टेप

steps:
  - label: ":xcode: iOS tests"
    agents:
      queue: "macos"
    commands:
      - "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"
      - "ditto -c -k --keepParent build/TestResults.xcresult build/TestResults.xcresult.zip"
    artifact_paths:
      - "build/TestResults.xcresult.zip"
    timeout_in_minutes: 30
    retry:
      automatic:
        - exit_status: -1
          limit: 2

exit_status: -1 वाला retry, Buildkite के command step उदाहरण से है। यह जॉब को तब दोबारा चलाता है, जब एजेंट खुद खो गया हो, तब नहीं जब कोई टेस्ट फ़ेल हुआ हो।

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

• launchctl कहता है Could not find domain for। Buildkite कहता है कि Mac पर किसी यूज़र का लॉग-इन होना ज़रूरी है। डेस्कटॉप पर लॉग-इन करें और सर्विस फिर लोड करें।
• Refusing to load formula ... from untrusted tap। brew trust buildkite/buildkite चलाएँ और दोबारा इंस्टॉल करें।
• एजेंट कनेक्ट नहीं होता। टोकन गलत है, या tags वाली queue key इस cluster में नहीं है।
• एजेंट clone नहीं कर पाता। key को उस यूज़र के ~/.ssh में रखें, जो एजेंट चलाता है।
• xcodebuild: error: Existing file at -resultBundlePath। बिल्ड वही checkout दोबारा इस्तेमाल करते हैं। ऊपर की तरह पहले bundle मिटाएँ।

बाद में अपग्रेड करने के लिए brew update && brew upgrade buildkite/buildkite/buildkite-agent@3 चलाएँ।

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

Buildkite आपकी अपनी मशीनों के लिए बना है, और हमेशा मौजूद Mac अपने कैश रखता है। Xcode 26.6 के साथ Wikipedia iOS ऐप पर हमारे बेंचमार्क में छोटे बदलाव के बाद जॉब को वॉर्म M6 पर 27 सेकंड लगे। नए GitHub-होस्टेड macos-26 रनर को 269 सेकंड लगे।

Buildkite के होस्टेड एजेंट कब काफ़ी हैं

Buildkite होस्टेड macOS एजेंट भी देता है। अक्टूबर 2026 में पढ़े गए उसके डॉक्स के मुताबिक, आप इन्हें होस्टेड queue बनाते समय चुनते हैं। अगर आप किसी मशीन की देखभाल नहीं करना चाहते, तो यह आसान रास्ता है। अगर आपको SLA, टोकन नियमों के लिए स्टैटिक IP, या एक से ज़्यादा रीजन चाहिए, तो भी MacRun सही नहीं है।

MacRun की तरफ़ के लिए दूसरे CI सिस्टम देखें। स्टेप में क्या चलाएँ, इसके लिए iOS CI/CD पाइपलाइन गाइड देखें।