Table of Contents

يفصل سير عمل الوكيل المحدود قراءة المستودع وقراءة API والتعامل مع الأسرار والكتابة عن بُعد. استخدم Git عبر Secure Shell (SSH) للوصول إلى المصدر، ومفتاح وصول Bitbucket للقراءة فقط للاستنساخ الآلي، وREST API للبيانات الوصفية، وخادم Model Context Protocol (MCP) للأدوات المعتمدة. خزّن المفاتيح الخاصة ورموز API في 1Password. اشترط موافقة بشرية قبل أي كتابة.

أهم النقاط

  • القراءة فقط افتراضيًا: استخدم مفتاح وصول للمستودع أو المشروع لاستنساخ الوكيل. لا يمنح أي منهما صلاحية push.
  • هوية شخصية: استخدم مفتاح SSH شخصيًا للعمل التفاعلي المرتبط بحساب مستخدم.
  • حفظ الأسرار: استخدم 1Password SSH Agent ليطلب Git عملية توقيع مصرحًا بها دون قراءة المفتاح الخاص.
  • مقصود CLI: اعتبر git وcurl وواجهة API صغيرة مدققة أدوات سطر أوامر Bitbucket العملية.
  • حد MCP: أتح أدوات قراءة ضيقة النطاق. عطّل أدوات الكتابة أو ضعها خلف مسار موافقة منفصل.
  • بوابة الكتابة: اسمح للوكيل بالفحص والمقارنة وإعداد التغيير. اطلب موافقة شخص قبل push أو pull request أو الدمج أو تحديث الإعدادات.

قبل البدء

المتطلبات: وصول إلى Bitbucket Cloud وGit وعميل OpenSSH و1Password 8 و1Password CLI وCLI مسجّل الدخول أو حساب خدمة معتمد، ومضيف MCP يتيح التحكم في الموافقة على الخوادم. خصص 45 دقيقة. مستوى الصعوبة متوسط.

استخدم مستودع اختبار في التجربة الأولى. استبدل كل عنصر نائب في الأمثلة. الأوامر أدناه أمثلة غير مختبرة. وهي لا تمثل حساب Bitbucket أو مستودعًا فعليًا.

الإصدارات: يقدم هذا المقال إرشادات تصميم، وليس دليل تشغيل مرتبطًا بإصدارات محددة. تحقق من إصدارات Git وOpenSSH و1Password CLI وTeamwork Graph CLI ومضيف MCP وخادم MCP المثبتة قبل الاختبار. أعدّ 1Password SSH Agent لنظام التشغيل الحالي قبل استخدام ssh-add -l.

أبقِ بيانات الاعتماد خارج الصدفة والسجلات وعناوين URL ومستودعات Git البعيدة والملفات المصدرية. استخدم عناصر نائبة مثل <workspace> و<repository> و<api-token> و<socket-path>. لا تلصق مفتاحًا خاصًا حقيقيًا في سجل الطرفية.

اختر حدود الوصول

يدعم Bitbucket Cloud مفاتيح الوصول على مستوى المستودع والمشروع ومساحة العمل. يغيّر النطاق أثر نسخ المفتاح. يوضح المقارنة الرسمية لمفاتيح الوصول اختلاف الأذونات مباشرة.

مسار الوصولالنطاقإمكانية الكتابةالاستخدام المناسب
مفتاح وصول المستودعمستودع واحدلااستنساخ الوكيل افتراضيًا
مفتاح وصول المشروعمستودعات ضمن مشروع واحدلامهام قراءة فقط لمجموعة صغيرة من المستودعات
مفتاح وصول مساحة العملمستودعات ضمن مساحة عمل واحدةنعمأتمتة خدمة مضبوطة بخطة كتابة منفصلة
مفتاح SSH شخصيمستودعات مسموح بها لمستخدم واحديتبع حساب المستخدمإدارة تفاعلية
رمز APIنطاقات API وصلاحيات حساب مرتبطة بمستخدميعتمد على النطاقاتقراءات REST API أو مهمة كتابة مؤقتة

ابدأ بأضيق حدود مناسبة. اختر مفتاح مستودع عندما يكفي مستودع واحد. اختر مفتاح مشروع عندما تشترك عدة مستودعات في مشروع واحد وتكفي صلاحية القراءة فقط. تعامل مع مفتاح مساحة العمل كهوية كتابة، لا كخيار افتراضي مريح.

أنشئ المفتاح الأقل صلاحية وسجّله عبر مسار إعدادات Bitbucket المناسب:

  1. افتح Repository settings ثم Access keys ثم Add key لمستودع واحد. الصق المفتاح العام وأبقِ المفتاح للقراءة فقط.
  2. افتح Project settings ثم Access keys ثم Add key عندما تحتاج عدة مستودعات إلى هوية قراءة محدودة بنطاق المشروع.
  3. استخدم مفتاح مساحة العمل فقط في مساحة مشتركة ذات تصميم كتابة معتمد. لا توفر مساحات العمل الشخصية مسارًا مماثلًا على مستوى مساحة العمل.
  4. سجّل اسم المفتاح ونطاقه وبصمة المفتاح العام ومالكه وتاريخ تدويره. احتفظ بالمفتاح الخاص في 1Password.

بعد التسجيل، نفّذ اختبار اتصال دقيقًا للقراءة فقط:

git ls-remote [email protected]:<workspace>/<repository>.git HEAD

الناتج المتوقع: مرجع commit واحد لـ HEAD. مثال غير مختبر. تثبت النتيجة الناجحة أن هوية SSH مسموحًا بها وصلت إلى المستودع المحدد. لكنها لا تثبت اختيار المفتاح المسجل أو وجود صلاحية كتابة. أعد الاختبار بعد إعداد مفتاح واحد لكل مستودع.

لمعلومات حفظ المفتاح الخاص وموافقة 1Password SSH Agent، راجع 1Password CLI وSSH Agent: تأمين مفاتيح SSH لوكلاء الذكاء الاصطناعي .

عرّف «Bitbucket CLI» بدقة

غالبًا ما تخلط عبارة Bitbucket CLI بين ثلاث واجهات مختلفة. أبقِها منفصلة.

  • Git CLI: تنقل git clone وgit fetch بيانات المستودع عبر SSH أو HTTPS. وتقارن git diff الملفات المحلية أو المراجعات.
  • عميل REST: يستدعي curl أو غلاف خضع للمراجعة واجهة Bitbucket Cloud Representational State Transfer (REST) API. واجهة API هي واجهة برمجية لطلب بيانات أو تنفيذ إجراءات. تسرد مرجعية Bitbucket Cloud REST API موارد المستودعات والمصدر والفروع وطلبات السحب والأنابيب والحالة.
  • Atlassian CLI: إن acli هو سطر أوامر Atlassian الرسمي. يشرح المستند التمهيدي المنتج، بينما تسرد مرجعية الأوامر واجهات admin وjira وfeedback وrovodev. لا توثق المرجعية أوامر Bitbucket Cloud.

لا توثق مرجعية أوامر acli الرسمية من Atlassian أوامر Bitbucket Cloud. لا تخترع أمرًا مثل acli bitbucket clone. استخدم Git لعمليات Git وREST API لبيانات Bitbucket Cloud.

Teamwork Graph CLI اختيارية

تنشر Atlassian أيضًا Teamwork Graph CLI، أو twg. توثق نظرة عامة و فهرس الأوامر مجموعات أوامر Bitbucket. أمر الإعداد هو:

twg setup

يغير أمر الإعداد حالة المصادقة المحلية. اتبع مطالبات الإصدار المثبت لإعداد رمز Bitbucket اختياريًا. مسار رمز Bitbucket في CLI منفصل عن Atlassian OAuth. اربط صيغة الأمر الدقيقة بالإصدار المثبت وفهرس الأوامر الحالي. استخدم ملف تعريف منفصلًا ورمزًا محدودًا ومهارات مثبتة خضعت للمراجعة وموافقة بشرية للأوامر التي تغيّر البيانات.

النتيجة المتوقعة، غير المختبرة: يتلقى ملف التعريف المعزول إعدادات مصادقة Bitbucket. سجّل حالة الملف السابق قبل الإعداد. عند التراجع، أزل بيانات الاعتماد المحفوظة عبر إجراء تسجيل الخروج أو إزالة الإعدادات الموثق للإصدار المثبت.

إذا وصف مشروع تابع لجهة خارجية نفسه بأنه Bitbucket CLI، فدقق مصدره وعملية إصداره ومجاميع التحقق ومسار تحديثه وتدفق المصادقة والنطاقات المطلوبة وجهات الشبكة ومعالجة السجلات وأوامر الكتابة. لا يثبت اسم الملف التنفيذي المألوف دعم المورّد أو أمان الأذونات.

أبقِ مفاتيح SSH تحت سيطرة 1Password

يوفر 1Password SSH Agent مفاتيح SSH المخزنة في 1Password لعملاء Git وSSH. ينفذ العميل طلب توقيع مصرحًا به. يبقى المفتاح الخاص داخل تطبيق 1Password، ويطلب 1Password الموافقة قبل استخدام عميل معتمد للمفتاح.

تؤدي مرجعية 1Password CLI دورًا مختلفًا. استخدم op للوصول المنضبط إلى العناصر ورموز API وحسابات الخدمة وإعداد الأتمتة. استخدم SSH Agent لتوقيع SSH. تجنب تصدير مفتاح خاص إلى ملف مؤقت لتسهيل سير عمل الوكيل.

تحقق من حالة CLI والوكيل محليًا باستخدام أوامر قراءة فقط:

op --version
ssh-add -l

الناتج المتوقع: إصدار 1Password CLI وبصمة مفتاح عام واحدة أو أكثر من الوكيل النشط. مثال غير مختبر. تعني نتيجة ssh-add -l الفارغة عدم توفر مفتاح عبر مقبس الوكيل المحدد.

لإنشاء مفتاح جديد، أنشئ عنصر SSH Key من نوع Ed25519 في 1Password أو استورد مفتاحًا أُنشئ بعملية محلية موثوقة. اختر تسمية وفق الغرض والنطاق وتاريخ التدوير. أضف المفتاح العام فقط إلى Bitbucket Cloud. يوضح دليل Linux لمفاتيح وصول المستودعات مسار إعدادات المستودع وقيد القراءة فقط.

تحقق أولًا من مفتاح مضيف Bitbucket

لا تثبت مصادقة مستخدم SSH هوية الخادم. يجب على العميل التحقق من مفتاح مضيف Bitbucket Cloud قبل إرسال طلب المصادقة. يسرد دليل Atlassian لـ SSH والتحقق بخطوتين مفاتيح المضيف العامة ويعرض نقطة النهاية الرسمية لاسترداد إدخالات known_hosts.

اجلب بيانات مفتاح المضيف العام للمقارنة:

curl --fail --silent --show-error https://bitbucket.org/site/ssh

الناتج المتوقع: أسطر OpenSSH في known_hosts لـ bitbucket.org. مثال غير مختبر. قارن المفتاح أو البصمة المستردة بنسخة موثوقة مستقلة قبل إضافة السطر إلى ~/.ssh/known_hosts.

استخدم التحقق الصارم من المضيف بعد إضافة الإدخال المعتمد:

Host bitbucket.org
    StrictHostKeyChecking yes
    UserKnownHostsFile ~/.ssh/known_hosts

لا تقبل تغيير مفتاح المضيف أثناء تشغيل الوكيل. أوقف التشغيل، وتحقق من سجل مفاتيح مضيف Bitbucket Cloud الحالي، وراجع إدخال known_hosts المحلي. تزيل الموافقة التلقائية حدًا أمنيًا قائمًا على المفتاح.

اختر مفتاحًا واحدًا لكل مستودع

غالبًا ما يحتوي الجهاز على عدة مفاتيح Bitbucket. يعرض وكيل SSH عام هويات متعددة أثناء اتصال واحد. وقد يرفض الخادم أو نهج يحد محاولات المصادقة عددًا قليلًا المفتاح الصحيح بعد فشل المفاتيح السابقة.

يستخدم دليل Atlassian لمفاتيح وصول مستودعات متعددة الخيار core.sshCommand في ملف إعداد Git للمستودع وincludeIf في إعداد Git العام. اتبع النمط نفسه لاستخدام مفتاح واحد لكل مستودع.

مثال محمول يعتمد على الملفات:

# .gitconfig inside one local repository
[core]
    sshCommand = ssh -o IdentitiesOnly=yes -i ~/.ssh/<repository-automation-key>
# ~/.gitconfig
[includeIf "gitdir:~/src/<repository>/"]
    path = ~/src/<repository>/.gitconfig

الكتلة أعلاه استثناء يستخدم ملف مفتاح خاص لهوية أتمتة مخصصة. وهي لا تعدّ 1Password SSH Agent. لاستخدام 1Password SSH Agent، اضبط قيمة IdentityAgent أو SSH_AUTH_SOCK الخاصة بالمنصة من دليل إعداد 1Password . تستخدم بعض إعدادات OpenSSH ملف .pub محددًا لهوية الوكيل. تحقق من دعم المنصة قبل ذلك. يحتاج الإعداد المعتمد على ملف إلى مسار المفتاح الخاص المطابق. لا تمرر ملف .pub مطلقًا إلى أمر يتوقع مادة مفتاح خاص، ولا تصدّر مفتاحًا خاصًا شخصيًا.

استخدم إعداد مستودع صريحًا عندما يحتاج الاستنساخ المحلي مفتاحًا معينًا. استخدم includeIf عندما يحتوي مجلد على عدة نسخ مستنسخة تشترك في حدود وصول واحدة. يعرض دليل المفاتيح المتعددة الإعدادين ضمن سير عمل Bitbucket.

استنسخ عبر Git باستخدام SSH:

git clone [email protected]:<workspace>/<repository>.git <local-directory>

الناتج المتوقع: ينشئ Git <local-directory> ويجلب المستودع عبر bitbucket.org. مثال غير مختبر. يسمح مفتاح وصول المستودع بالاستنساخ والسحب فقط.

استخدم رموز API لقراءات REST محدودة

استخدم SSH لنقل Git. واستخدم REST API للبيانات الوصفية أو العمليات خارج نقل Git. يسرد دليل أذونات رموز API نطاقات المستودع مثل Read وWrite وAdmin وDelete. يقابل Repository Read النطاق read:repository:bitbucket ولا يتضمن الوصول إلى طلبات السحب.

فضّل رمز وصول لمستودع أو مشروع Bitbucket لأتمتة القراءة عندما تدعم الوجهة نقطة النهاية المطلوبة. يحتفظ رمز API المرتبط بمستخدم بوصول الحساب الأوسع. استخدم رمز مساحة العمل فقط إذا سجلت المهمة هذا الحد الأوسع. راجع دليل رموز الوصول إلى Bitbucket قبل اختيار نوع الرمز.

ابدأ لمسار قراءة الوكيل بـ read:repository:bitbucket. أضف read:pullrequest:bitbucket فقط عندما يحتاج الوكيل بيانات طلبات السحب. لا تضف نطاقات مساحة العمل أو الأنابيب إلا إذا حدد سجل المهمة نقطة النهاية والنتيجة. تحتاج نطاقات الكتابة والإدارة إلى مسار موافقة منفصل.

أنشئ كل رمز API لغرض واحد، وحدد تاريخ انتهاء، وسجّل التاريخ في سجل التدوير، واستبدل الرمز قبل انتهاء صلاحيته. يتطلب دليل إنشاء رمز API من Atlassian اسمًا وتاريخ انتهاء واختيار تطبيق ونطاقات. يظهر الرمز مرة واحدة بعد إنشائه.

احتفظ بالقيمة في 1Password أو سر بيئة تشغيل مُدار. لا تضعها في عنوان URL بعيد. مرر رمز bearer عبر متغير بيئة للعملية التي تحتاج قراءة واحدة فقط:

op run --env-file=/path/to/agent.env -- \
sh -c 'curl --fail --silent --show-error \
  --request GET \
  --url "https://api.bitbucket.org/2.0/repositories/<workspace>/<repository>" \
  --header "Authorization: Bearer ${BITBUCKET_API_TOKEN}" \
  --header "Accept: application/json"'

أبقِ /path/to/agent.env خارج المستودع. خزّن مرجعًا مثل BITBUCKET_API_TOKEN=op://synthetic-vault/synthetic-api-token/credential في الملف. يحل op run المرجع ويكشف القيمة لعملية curl الفرعية طوال عمر العملية. لا يمنع ذلك العملية الفرعية من قراءة قيمة متغير البيئة أو تسجيلها. لا تستبدل العنصر النائب برمز حرفي.

الناتج المتوقع: بيانات JSON الوصفية للمستودع المحدد. مثال غير مختبر. يجب ألا يصبح العنصر النائب رمزًا حقيقيًا في ملف مودع أو سجل.

للأتمتة الأطول، دع 1Password يحقن سرًا في بيئة العملية عبر تدفق CLI أو حساب الخدمة المدعوم. اجعل مدة الرمز ملائمة للمهمة. ألغِ الرمز إذا انتهت المهمة مبكرًا أو تغير مالك المضيف.

خصص لـ MCP سطح قراءة صغيرًا

استخدم مواصفات MCP الحالية و قواعد التفويض عند مراجعة خادم جديد. تحتاج خوادم HTTP إلى فحوص جمهور الرمز ومعالجة واضحة للاستجابتين 401 و403.

يحصل مضيف MCP على موافقة المستخدم. ويحافظ العميل على اتصال بخادم واحد. ويعرض الخادم أدوات أو موارد أو prompts. تعامل مع كل خادم كرمز غير موثوق حتى تجتاز مراجعة مصدره ونقله وحسابه وأذوناته.

عنوان مواصفات 2025-06-18 في الفقرة التالية يعود إلى إصدار تاريخي. استخدم مواصفات 2026-07-28 الحالية للمراجعات الجديدة.

تحدد مواصفات MCP الاتصال بين مضيف MCP والعميل والخادم. يعرض الخادم أدوات أو موارد أو prompts عبر البروتوكول. توحد MCP تنسيق الاتصال. لكن المضيف وتنفيذ الخادم والحساب ونطاق الرمز وسياسة الموافقة هي التي تحدد ما يصل إليه الاستدعاء.

استخدم خادم MCP كمحوّل ضيق النطاق فوق Git وBitbucket Cloud REST API.

احمِ هذا المحول من تمرير الرموز وتزوير الطلبات من جانب الخادم (SSRF) وسلوك الوكيل المرتبك. يتيح SSRF للخادم إرسال طلبات إلى وجهات غير مقصودة. يحدث سلوك الوكيل المرتبك عندما يستخدم الخادم صلاحيات أوسع نيابة عن مستدعٍ. واحمِ النظام أيضًا من الخوادم المحلية الخبيثة وإعادات توجيه OAuth غير الآمنة والردود المفرطة الحجم لبيانات المصدر. ثبّت أصول Bitbucket المسموح بها ومعرّفات المستودعات. شغّل الخوادم المحلية في بيئة معزولة تحت حساب نظام تشغيل مخصص. احجب الأسرار من نتائج الأدوات والسجلات.

يصف هذا القسم تصميمًا، لا إعداد MCP مختبرًا. لم يحدد عميلًا أو خادمًا أو نقلًا أو إصدارًا أو مجموعة اختبارات. تحقق من خادم قراءة فقط ضمن ملف تعريف اختبار منفصل قبل توصيل وكيل بمستودع إنتاج.

تشمل أدوات القراءة النموذجية:

الأداةالنتيجة المحدودة
get_repository_metadataيعيد بيانات مستودع واحد الوصفية
read_source_fileيقرأ مسارًا واحدًا في مراجعة محددة
list_branchesيسرد فروع مستودع واحد
get_pull_requestيعيد طلب سحب واحدًا بعد منح الرمز نطاق قراءة طلبات السحب
get_build_statusيعيد بيانات حالة commit واحد

تصف هذه الأسماء تصميمًا. وليست أسماء أوامر Atlassian. امنع الخادم من قبول عناوين URL عشوائية أو أوامر صدفة عشوائية أو رموز خام أو طلبات تصدير مفاتيح خاصة أو معرّفات مستودعات بلا قيود.

اضبط الأذونات على أربع طبقات:

  1. Bitbucket Cloud: مفتاح قراءة للمستودع أو المشروع في Git، مع أصغر نطاقات رمز API لقراءات REST.
  2. 1Password: خزنة واحدة أو حساب خدمة للمهمة، من دون مسار لتصدير المفاتيح الخاصة.
  3. خادم MCP: قائمة سماح لأدوات القراءة ونقاط نهاية Bitbucket Cloud ثابتة والتحقق من المدخلات ومهل زمنية وسجلات محجوبة الأسرار.
  4. مضيف MCP: موافقة المستخدم على الخادم وكل إجراء يتيح الكتابة، مع تعطيل أدوات الكتابة في ملف التعريف الافتراضي.

تثبت قائمة أدوات MCP اكتشاف الأدوات. ولا تثبت التفويض أو صحة النطاق أو أمان معالجة المدخلات أو صحة النتيجة.

نظّم سير عمل الوكيل

أبقِ سير العمل واضحًا. تقدم كل مرحلة أدلة للمرحلة التالية.

المرحلةإجراء الوكيلالإذنبوابة بشرية
التحضيرقراءة الإعداد وسجل مفتاح المضيف واسم المفتاح ونطاق الرمز وانتهائهقراءة محليةالموافقة على سجل الإعداد
الفحصاستنساخ أو جلب عبر Git باستخدام SSH والاستعلام عن بيانات REST الوصفيةقراءة المستودع وAPIلا شيء بعد الإعداد
التحليلقراءة الملفات والفروع وطلبات السحب وحالة البناء عبر أدوات معتمدةأدوات MCP للقراءة فقطلا شيء للقراءات المحدودة
إعداد التغييرإنتاج رقعة أو خطة فرع أو مسودة طلب سحب ضمن مساحة عمل محليةكتابة محلية فقطمراجعة diff والهدف
اعتماد الكتابةعرض الإجراء البعيد الدقيق ونطاقه وخطة التراجعلا كتابة بعيدة بعدموافقة بشرية
تنفيذ الكتابةدفع فرع أو إنشاء طلب سحب أو استدعاء نقطة نهاية كتابةهوية كتابة قصيرة العمرتأكيد كل إجراء
التحقققراءة commit أو طلب السحب أو الحالة الناتجةالعودة إلى القراءة فقطتأكيد النتيجة المتوقعة

ينبغي أن يتوقف ملف تعريف الوكيل الافتراضي بعد التحليل أو إعداد التغيير. وينبغي أن يستخدم ملف كتابة منفصل رمزًا أو مفتاحًا مختلفًا وانتهاءً قريبًا وهدفًا ثابتًا وطلب موافقة. لا يستطيع مفتاح وصول المستودع تنفيذ خطوة الكتابة، وهذا ينشئ حدًا تقنيًا مفيدًا.

التراجع والإزالة

ابدأ التراجع بإزالة الوصول، ثم نظف الإعدادات المحلية:

  1. أزل مفتاح وصول المستودع أو المشروع أو مساحة العمل من صفحة إعدادات Bitbucket المطابقة.
  2. ألغِ رمز API الخاص بالمستودع أو المشروع أو مساحة العمل أو المستخدم من صفحة الأمان المطابقة في Bitbucket.
  3. أزل بيانات اعتماد Teamwork Graph المحفوظة عبر إجراء المصادقة الموثق لإصدار CLI المثبت. احتفظ ببيانات الاعتماد السابقة في مدير الأسرار المعتمد فقط. تحقق من أن ملف التعريف المعزول لم يعد يعرض بيانات اعتماد الاختبار.
  4. أزل ملف .gitconfig الخاص بالمستودع وإدخال includeIf بعد انتهاء الاختبار. أبقِ إعداد Git غير المرتبط دون تغيير.
  5. أزل فقط سطر مفتاح مضيف Bitbucket الذي تحققت منه وأضفته للاختبار. احتفظ بمفاتيح المضيف الأخرى المعتمدة.
  6. أزل ملف agent.env الخارجي والمخرجات المؤقتة. أزل إدخال خادم MCP من إعدادات المضيف ثم أعد تشغيل المضيف.

سجّل كل إزالة واسم المنفذ ووقتها. دوّر المفتاح أو الرمز إذا ظهرت قيمة في سجل أو سجل عملية أو نص تفريغ غير متوقع.

حلقة قراءة عن بُعد مع تحديث المراجع المحلية

استخدم حلقة صغيرة لفحص المستودع دوريًا:

LOCAL_REPO="<local-directory>"
git -C "$LOCAL_REPO" fetch --no-tags
git -C "$LOCAL_REPO" status --short --branch
git -C "$LOCAL_REPO" log -1 --format='%H %ad %s' --date=iso-strict

يشير HEAD إلى المرجع المحدد حاليًا في المستودع. تثبت النتيجة الناجحة أن هوية SSH مسموحًا بها وصلت إلى المستودع المحدد. لكنها لا تثبت أي مفتاح تم اختياره أو وجود صلاحية push.

الناتج المتوقع: نتيجة fetch وحالة الفرع وسطر commit واحد. مثال غير مختبر. لا يكتب fetch إلى البعيد، لكنه يحدث المراجع المحلية وFETCH_HEAD. ولا تنفذ الحلقة push أو تبديل الفروع.

ينبغي أن يعرض خادم MCP حد القراءة نفسه عبر عمليات مسماة. ينبغي لغلاف shell محلي أو أداة MCP رفض فعل كتابة قبل إرسال الطلب. سجّل اسم الأداة والعنصر النائب للمستودع والمراجعة وفئة النتيجة والمدة. احجب الرموز وملفات تعريف الارتباط والمسارات الخاصة ومحتوى الملفات إلا إذا احتاجت المهمة صراحةً إلى ملف واحد.

استكشاف الأخطاء وإصلاحها

Permission denied (publickey)

تحقق من مقبس الوكيل النشط والمفتاح العام المحدد وإدخال مفتاح وصول المستودع وIdentitiesOnly. يجب تسجيل مفتاح المستودع في المستودع أو المشروع المستهدف. يحتاج المفتاح الشخصي إلى أذونات الحساب. لمفتاح مساحة العمل حد كتابة مختلف.

تقديم مفتاح المستودع الخطأ

استخدم مفتاحًا واحدًا لكل مستودع عبر core.sshCommand، أو اجمع النسخ المستنسخة ضمن مجلد يتحكم به includeIf. اعرض مفاتيح الوكيل عبر ssh-add -l. إذا توفر عدد كبير من مفاتيح 1Password، فاستخدم محدد هوية صريحًا أو إشارة SSH مرجعية من 1Password. يوثق دليل 1Password Agent اعتبارات عدد المفاتيح والإشارات المرجعية.

أبلغ SSH عن تغيير مفتاح المضيف

أوقف الوكيل. لا تحذف known_hosts كخطوة أولى. قارن سجل مفاتيح مضيف Bitbucket Cloud الحالي بالإدخال المحلي عبر قناة مستقلة. لا تزل الإدخال أو تستبدله إلا بعد نجاح المقارنة.

تعيد API الاستجابة 401 أو 403

تحقق من انتهاء الرمز ونوعه ونطاق نقطة النهاية وحدود الحساب أو مساحة العمل. لا يتضمن نطاق قراءة المستودع طلبات السحب. تحتاج نقطة نهاية الكتابة إلى نطاق كتابة وملف كتابة معتمد. لا توسع النطاقات قبل تحديد نقطة النهاية التي أخفقت.

تعيد API بيانات المستودع دون طلبات سحب

أضف أصغر نطاق قراءة لطلبات السحب إلى رمز جديد أو مدوّر. لا تستخدم رمز مستخدم واسعًا مرة أخرى لخادم MCP للقراءة فقط.

يسرد خادم MCP الأدوات لكن يفشل الاستدعاء

افصل بين تسجيل الخادم والاتصال واكتشاف الأدوات والتنفيذ والتحقق من النتيجة. افحص سجل الخادم دون كشف الرمز. تحقق من نقطة النهاية وشكل الإدخال. أعد المحاولة مرة واحدة بعد التحقق من الاتصال. علّم العملية بأنها غير مكتملة إذا أخفقت المحاولة الثانية.

تطلب CLI تابعة لجهة خارجية وصولًا واسعًا إلى Bitbucket

أوقف التثبيت. قارن الوصول المطلوب بسجل المهمة. راجع المصدر وتوقيعات الإصدارات أو مجاميع التحقق وجهات الشبكة وتخزين الأسرار وسلوك الكتابة. لا تثبت مرجعية أوامر Atlassian CLI الرسمية دعم ملف Bitbucket تنفيذي تابع لجهة خارجية.

الخطوات التالية

أنشئ سجل وصول موجزًا يتضمن نطاق المستودع أو المشروع واسم المفتاح وتاريخ التحقق من مفتاح المضيف ونطاقات API وانتهاء الرمز ومالك 1Password وقائمة أدوات MCP المسموح بها وسياسة السجلات ومعتمد الكتابة.

نفّذ استنساخًا واحدًا للقراءة فقط وقراءة واحدة لبيانات REST الوصفية وقراءة واحدة لأداة MCP مع عناصر نائبة في النص. قارن النتائج. أبقِ ملف تعريف الوكيل للقراءة فقط إلى أن تجتاز السجلات والمخرجات المراجعة.

عند وصول مهمة كتابة، أعدّ diff محليًا أولًا. اعرض الفرع الهدف والمسارات المتغيرة وطريقة API المطلوبة ونطاق الرمز وخطوة التراجع. استخدم هوية كتابة منفصلة وقصيرة العمر بعد موافقة بشرية على الإجراء الدقيق فقط.