Buildkite

buildkite-mcp-server

Model Context Protocol (MCP) सर्वर, जो AI टूलिंग और एडिटरों को Buildkite डेटा (पाइपलाइन, बिल्ड, जॉब, टेस्ट) उपलब्ध कराता है।

पूरा दस्तावेज़ buildkite.com/docs/apis/mcp-server पर उपलब्ध है।

---

सीमित अनुमतियों के साथ बिल्ड दोबारा चलाना

retries टूलसेट, व्यापक बिल्ड-लेखन पहुँच के बिना विफलताओं की जाँच करने और जॉब दोबारा चलाने की सुविधा देता है। इसमें list_builds, get_build, wait_for_build, list_jobs, get_job, search_logs, tail_logs, read_logs, retry_job, और retry_failed_jobs शामिल हैं। इसके लिए read_builds, read_build_logs, और retry_builds स्कोप आवश्यक हैं, write_builds नहीं।

buildkite-mcp-server stdio --enabled-toolsets retries

retry_failed_jobs केवल इन्फ्रास्ट्रक्चर विफलताओं पर जॉब दोबारा चलाता है; उन्हें चलाए बिना प्रस्तावित रीट्राई देखने के लिए इसका dry_run विकल्प इस्तेमाल करें। retry_job किसी खास जॉब को दोबारा चलाता है। दोनों बदलाव करने वाले टूल हैं और --read-only में शामिल नहीं हैं। यह टूलसेट create, rebuild, cancel या unblock ऑपरेशन उपलब्ध नहीं कराता। मौजूदा रीट्राई टूल builds में उपलब्ध रहते हैं; builds या all चुनने पर भी अन्य बदलावों के लिए write_builds आवश्यक है।

Buildkite API में टोकन के स्वामी द्वारा retry_builds स्वीकार किए जाने के लिए RetryBuildsScope सुविधा सक्षम होनी चाहिए; मौजूदा write_builds टोकन स्वीकार किए जाते रहेंगे। होस्ट किया गया MCP OAuth इस टूलसेट को /mcp/x/retries के ज़रिए चुन सकता है, जब होस्ट किया गया सर्वर इसे शामिल करने वाली रिलीज़ अपना ले। अनुरोध हेडर के ज़रिए टूलसेट चुनने से मौजूदा टोकन के OAuth स्कोप नहीं बदलते।

लाइब्रेरी उपभोक्ताओं के लिए, WithDisabledToolsets और HTTP फ़ैक्टरी के अक्षम टूलसेट, ओवरलैप करने वाले समूहों के ज़रिए भी, उन टूलसेट के सभी सदस्यों को बाहर रखते हैं। उदाहरण के लिए, logs को अक्षम करने से retries के लॉग टूल भी हट जाते हैं; retries को अक्षम करने से उसके निरीक्षण और रीट्राई टूल अन्य समूहों से भी हट जाते हैं।

---

GitHub Actions पाइपलाइन कॉन्फ़िगर करना

create_pipeline और update_pipeline, GitHub provider_settings और branch_configuration स्वीकार करते हैं। create पर API डिफ़ॉल्ट इस्तेमाल करने या update पर उन्हें अपरिवर्तित रखने के लिए provider keys छोड़ दें। स्पष्ट रूप से दिया गया false जस का तस रखा जाता है। उन्हें साफ़ करने के लिए filter_condition या pull_request_branch_filter_configuration को null पर सेट करें; खाली स्ट्रिंग खाली स्ट्रिंग के रूप में भेजी जाती है। मौजूदा branch filter साफ़ करने के लिए update पर branch_configuration: null सेट करें। create पर, छोड़ा गया, null या खाली branch filter API के null डिफ़ॉल्ट का इस्तेमाल करता है। पूर्ण get_pipeline और list_pipelines प्रतिक्रियाएँ समर्थित GitHub सेटिंग्स को जस का तस रखती हैं। go-buildkite की प्रतिक्रिया स्ट्रिंग null और खाली मान में अंतर नहीं बताती, इसलिए readback से आंशिक अपडेट दोबारा न बनाएँ।

मैन्युअल GitHub Actions सेटअप का पालन करें। साथी workflow builds को छोड़ने या रद्द करने से बचने के लिए branch-व्यापी skip_queued_branch_builds और cancel_running_branch_builds को false रखें। create_webhook: false का इस्तेमाल करें: provider सेटिंग्स कोई समर्पित GitHub Actions trigger या उसका webhook उपलब्ध नहीं करातीं, और मौजूदा webhook टूल पारंपरिक repository webhooks बनाते हैं। सर्वर-साइड सुविधा उपलब्धता और टोकन अनुमतियाँ फिर भी लागू होती हैं; सेटिंग्स स्वीकार होना workflow के चलने का प्रमाण नहीं है।

create पर, गैर-रिक्त configuration या स्वीकृत pipeline_template_uuid दें, दोनों नहीं। update पर, असाइनमेंट बनाए रखने के लिए pipeline_template_uuid छोड़ दें, configuration के बिना template असाइन करने के लिए UUID दें, या उसे हटाने के लिए null भेजें। हटाने के साथ replacement configuration भी दिया जा सकता है; API कॉन्फ़िगरेशन आवश्यकताओं और संगठन की template नीति लागू करता है। पूर्ण pipeline प्रतिक्रियाएँ असाइन किए गए UUID बनाए रखती हैं; जब प्रतिक्रिया में असाइनमेंट null या अनुपस्थित हो, तो go-buildkite फ़ील्ड छोड़ देता है।

पारंपरिक GitHub webhook प्रोसेसिंग का निरीक्षण करने या उसे बदलने के लिए get_pipeline_github_webhook_processing, enable_pipeline_github_webhook_processing, और disable_pipeline_github_webhook_processing का इस्तेमाल करें। ये POST webhook creation endpoint के बजाय GET/PUT/DELETE github-webhooks का इस्तेमाल करते हैं। ये repository webhooks नहीं हटाते और न ही समर्पित GitHub Actions triggers बदलते हैं। प्रतिक्रियाएँ enabled और nullable disabled_at तथा disabled_by मेटाडेटा जस का तस रखती हैं; disabled_by उपयोगकर्ता का नाम है। तीनों के लिए Full Access, GitHub या GitHub Enterprise pipeline, और expanded webhook triggers में संगठन का नामांकन आवश्यक है। GET के लिए read_pipelines आवश्यक है; enable/disable के लिए write_pipelines आवश्यक है और read-only मोड में ये उपलब्ध नहीं होते। 404 का अर्थ यह हो सकता है कि नियंत्रण उपलब्ध नहीं हैं, न कि pipeline मौजूद नहीं है। API त्रुटियाँ लौटाई जाती हैं; विफलता को disabled स्थिति नहीं माना जाता।

इन अनुबंधों की जाँच स्थानीय synthetic HTTP fixtures के साथ की जाती है। होस्ट की गई उपलब्धता, अनुमतियों, स्थायित्व और workflow निष्पादन की अलग से पुष्टि आवश्यक है; स्थानीय सफलता, तैनात समर्थन का प्रमाण नहीं है। समर्पित GitHub Actions trigger प्रबंधन शामिल नहीं है।

---

बिल्ड की तुलना करना

investigations टूलसेट का read-only compare_builds टूल ऐसे सवालों के जवाब देता है, जैसे “इस बिल्ड के main पर पिछली बार सफल होने के बाद क्या बदला?” org_slug, pipeline_slug, और लक्ष्य build_number दें। यह उसी pipeline और सटीक branch पर, पहले बनाया गया सबसे नया build चुनता है जो इस समय passed है। यह आवश्यक नहीं कि baseline, लक्ष्य शुरू होने के समय भी passed रहा हो। उसी pipeline के किसी खास build से तुलना करने के लिए baseline_build_number दें; इसमें failed build या किसी दूसरी branch का build भी शामिल हो सकता है।

प्रतिक्रिया baseline और चयन नियम बताती है, सभी jobs के परिणामों की गिनती करती है, और अधिकतम 100 job तुलनाएँ लौटाती है; इनमें नए failing, recovered और अब भी failing steps को प्राथमिकता दी जाती है। मिलान step keys, job type, matrix values और parallel index/total के आधार पर होता है। जब दोनों jobs में keys न हों, तो यह सटीक गैर-रिक्त नाम और type, group key, matrix values तथा parallel index/total के आधार पर fallback करता है, लेकिन केवल तब जब यह संयोजन दोनों builds में अद्वितीय हो। मिलान किए गए जोड़े match_method: "step_key" या "name_fallback" दिखाते हैं; fallback matches के साथ चेतावनी होती है कि वे heuristic हैं। बिना नाम वाले, बिना key के jobs और दोहराई गई identities का मिलान नहीं होता। स्पष्ट keys होने पर नामों के आधार पर fallback कभी नहीं होता, भले ही builds के बीच कोई key जोड़ी, हटाई या बदली गई हो। Added/removed का अर्थ है कि job identity केवल एक build में मौजूद है; इसलिए बिना key वाले jobs का नाम बदलने या matrix values अथवा parallelism बदलने से भी added/removed प्रविष्टियाँ बन सकती हैं। दोबारा चलाए गए attempts शामिल नहीं होते; अंतिम attempt की स्थितियाँ और retry की गिनती दिखाई देती है।

निष्पादन समय और अंतर केवल अंतिम attempts के लिए होते हैं। Scheduling time scheduled_at से started_at तक का समय है, dependency या manual waiting का नहीं। ये build के wall-clock समय की तुलनाएँ या कुल retry लागत नहीं हैं। अनुपस्थित या असंगत timestamps होने पर संबंधित timing शामिल नहीं की जाती। अधूरे builds को स्पष्ट रूप से बदलते snapshots के रूप में पहचाना जाता है।

soft_failed में किसी भी बदलाव को state_changed के रूप में रिपोर्ट किया जाता है: soft और hard failures के बीच बदलाव, भले ही दोनों jobs की स्थिति failed हो, और passed तथा soft-failed jobs के बीच बदलाव। इन्हें कभी newly_failing या recovered के रूप में रिपोर्ट नहीं किया जाता, क्योंकि soft failure build को रोकता नहीं है। passed baseline build में soft-failed jobs हो सकते हैं।

डिफ़ॉल्ट रूप से, अधिकतम तीन नए blocking failures के लिए उनके आखिरी 20 log entries शामिल होते हैं: पहले newly_failing jobs, फिर state_changed jobs जो अब hard failures हैं, जैसे baseline में soft-failed job। हर log में log content अधिकतम 8 KiB तक सीमित होता है। Logs छोड़ने के लिए include_logs: false सेट करें। HTTP 401 authentication errors को छोड़कर, log errors से तुलना नहीं हटती; ये त्रुटियाँ सर्वर के reauthentication path से आगे भेजी जाती हैं। इस टूल के लिए read_builds और read_build_logs स्कोप आवश्यक हैं। आगे जाँच के लिए get_build_failure_summary या tail_logs का इस्तेमाल करें; किसी साझा failing step से साझा root cause साबित नहीं होता और न ही retry सुरक्षित हो जाता है।

Baseline खोज अधिकतम 500 उम्मीदवारों तक सीमित है। यदि कोई नहीं मिलता, तो प्रतिक्रिया बताती है कि तुलना नहीं की गई और स्पष्ट baseline देने को कहती है। हर build की job inventory अधिकतम 1,000 jobs तक सीमित है; इससे बड़ी inventories भ्रामक आंशिक added/removed परिणाम देने के बजाय त्रुटि लौटाती हैं। आउटपुट में छोड़ी गई चीज़ों की जानकारी, परिणामों की पूरी गिनती से अलग दी जाती है।

---

Test Engine workflows का निरीक्षण करना

tests टूलसेट के read-only list_test_workflows और get_test_workflow टूल किसी suite के कॉन्फ़िगर किए गए monitors, filters, alarm/recovery actions, और links दिखाते हैं। दोनों के लिए read_suites और suite तक पहुँच आवश्यक है। workflows की सूची पाने के लिए org_slug और test_suite_slug (slug या UUID) दें:

{"org_slug": "acme", "test_suite_slug": "backend"}

किसी एक workflow का निरीक्षण करने के लिए, उसी organization और suite के साथ get_test_workflow कॉल करें और item का id को workflow_id के रूप में दें।

चिह्नित tests खोजने के लिए कॉन्फ़िगर किए गए labels के साथ list_tests का इस्तेमाल करें; केवल labels से flakiness की रैंकिंग नहीं होती। Workflows कॉन्फ़िगरेशन बताते हैं, इस बात का प्रमाण नहीं कि कोई action चला या event history क्या है। कॉलर की API अनुमतियाँ चाहे जो हों, दोनों टूल webhook endpoints को हमेशा [REDACTED] से बदल देते हैं।

---

Test Engine span aggregates का निरीक्षण करना

read-only tests टूलसेट में चार span aggregate टूल शामिल हैं, जिनके लिए read_suites आवश्यक है:

• list_span_aggregate_scopes: कुल अवधि के आधार पर instrumentation scopes की सूची पाने के लिए org_slug, test_suite_slug, और वैकल्पिक period दें। OTel trace ingestion सक्षम होना चाहिए। Aggregates की सटीकता hourly होती है और retention एक महीने की होती है; अनुरोधित अवधि संगठन की API history allowance के भीतर होनी चाहिए।
• list_span_aggregate_scopes_for_build: build के दिखाई देने वाले suites में instrumentation scopes की सूची पाने के लिए org_slug और build_uuid दें। इसके लिए OTel trace ingestion और build की pipeline तक पहुँच आवश्यक है।
• list_span_aggregate_names: किसी suite के span-name statistics पाने के लिए org_slug, test_suite_slug, और scope_name दें। यह list_span_aggregate_scopes जैसी ही period values और retention का समर्थन करता है, साथ ही नीचे बताए गए sort और limit विकल्पों का भी। इसके लिए OTel trace ingestion आवश्यक है।
• list_span_aggregate_names_for_build: build के दिखाई देने वाले suites में span-name statistics पाने के लिए org_slug, build_uuid (pipeline build number नहीं), और scope_name दें। बिना नाम वाले scope के लिए खाली string इस्तेमाल करें। इसके लिए build की pipeline तक पहुँच आवश्यक है। वैकल्पिक sort का डिफ़ॉल्ट -total है, और limit का डिफ़ॉल्ट 20 है (अधिकतम 100)। परिणाम को पूर्ण मानने से पहले span_names_truncated जाँचें।

अवधियाँ nanoseconds में होती हैं। कुल span durations का योग है, wall-clock समय का माप नहीं; p50 और p95 मान अनुमानित हैं। कोई भी span aggregate टूल paginated नहीं है। दोनों span-name टूल बिना नाम वाले scope के लिए खाली scope_name स्वीकार करते हैं और अधिक नाम मौजूद होने पर span_names_truncated लौटाते हैं।

---

लाइब्रेरी का उपयोग

इस मॉड्यूल के निर्यात किए गए Go API को अस्थिर और इस परियोजना के विकास के साथ breaking changes के अधीन माना जाना चाहिए।

---

सुरक्षा

MCP सर्वर को सुरक्षित वातावरण में चलाने के लिए, हम इसे container में चलाने की सलाह देते हैं।

यह image cgr.dev/chainguard/static से बनाई गई है और unprivileged user के रूप में चलती है।

HTTP मोड में identity headers आगे भेजना

Self-hosted HTTP deployments, हर आने वाले MCP अनुरोध से चुने गए headers को Buildkite API तक आगे भेज सकते हैं:

BUILDKITE_API_TOKEN=bkua_xxx \
  buildkite-mcp-server http \
  --passthrough-http-header X-User-Identity

एक से अधिक headers की अनुमति देने के लिए --passthrough-http-header दोहराएँ, या comma-separated BUILDKITE_PASSTHROUGH_HTTP_HEADERS मान सेट करें। केवल स्पष्ट रूप से अनुमत headers ही आगे भेजे जाते हैं, और केवल BUILDKITE_BASE_URL द्वारा कॉन्फ़िगर किए गए origin तक। दूसरे स्थान पर redirect किए गए अनुरोधों से ये हटा दिए जाते हैं।

हर MCP अनुरोध को उसके अपने Buildkite API token से authenticate करने के लिए, Authorization की अनुमति दें और process-wide token छोड़ दें:

BUILDKITE_PASSTHROUGH_HTTP_HEADERS=Authorization \
  buildkite-mcp-server http

इस मोड में, हर /mcp अनुरोध में ठीक एक गैर-रिक्त Authorization header होना चाहिए। Credentials न होने पर HTTP 401 लौटता है; सर्वर कभी भी साझा API token का fallback नहीं करता। MCP सर्वर के सामने मौजूद reverse proxy, callers को authenticate करने और आगे भेजे जाने वाले identity headers सेट या validate करने के लिए ज़िम्मेदार है। stdio मोड में हेडर पासथ्रू उपलब्ध नहीं है। जॉब लॉग उपलब्ध कराने से पहले, सर्वर सत्यापित करता है कि मौजूदा कॉलर जॉब लॉग तक पहुँच सकता है। यह जाँच हर लॉग-टूल अनुरोध के लिए की जाती है, भले ही लॉग डेटा पहले से कैश किया गया हो।

---

योगदान

विकास संबंधी दिशानिर्देश DEVELOPMENT.md में हैं।

---

लाइसेंस

MIT © Buildkite

SPDX-License-Identifier: MIT