تخطَّ إلى المحتوى
تسجيل الدخولاطلب حساب

متتبّعات المهام: GitHub وLinear وJira

أغلب التقارير اللي تعدّي الفرز تتحوّل لشغل. وتكامل متتبّع المهام يسدّ الفجوة بين «انلقطت الملاحظة» و«انجدول الشغل»: تربط GitHub Issues أو Linear أو Jira مرّة وحدة، توجّهه للمشاريع اللي تحتاجه، ومن أي تقرير يقدر المُفرِز يفتح تذكرة حقيقية بضغطة. والتقرير يحتفظ برابط رجوع حيّ. وأول ما توجّه webhook متتبّعك لـuMarker، قفل التذكرة ينقل التقرير معها.

تربط مرّة، وتوجّه لكل مشروع

الاعتماد يُدخَل مرّة وحدة للحساب كله. وبعدها كل مشروع يرتبط فيه، ويقدر يشير لمستودع أو فريق أو مشروع Jira مختلف.

تذكرة بضغطة

من التقرير، زرّ إنشاء تذكرة ينقل العنوان والوصف ورابط لقطة موقّع (وعلى GitHub التسميات كمان) لتذكرة جديدة.

الحالة ترجع لك

webhook من المتتبّع ينقل تقرير uMarker مع التذكرة: done ← محلول، reopened ← قيد التنفيذ، و— في GitHub وLinear — cancelled ← مؤرشف.

ما يكرّر، ويفشل نظيف

التقرير المرتبط ما ينربط مرّتين. ولو رفض المتتبّع الطلب، ما ينحفظ شي ناقص، والتقرير يقول لك كذا بكلام واضح. وسبب المتتبّع نفسه ينحفظ على الاتصال.

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

  • اربط عبر Jira / GitHub / Linear: تسجّل دخولك عند المزوّد وتوافق، وخلاص. ما تنسخ ولا تكتب شي.
  • رمز API: تلصق الرمز، وuMarker ما تسألك إلا عن اللي الرمز ما يقدر يقوله لها، والباقي تلقاه بنفسها.

وبالطريقين، الوجهة (المشروع ونوع التذكرة، أو المستودع، أو الفريق) تختارها من قائمة تنجاب بدخولك، وما تكتبها أبداً. وuMarker تفحص اختيارك، وتخزّن الاعتماد مشفّراً، وتعلّم الاتصال active.

لمّا يكون مشغّل منصّتك ضابط تسجيل الدخول عند المزوّد (شوف للمشغّلين)، تطلع لك على البطاقة اربط عبر Jira أو اربط عبر GitHub أو اربط عبر Linear:

  1. اضغط اربط عبر …. النافذة تروح لصفحة تسجيل الدخول عند المزوّد.

  2. سجّل دخولك ووافق على الوصول. ترجع للوحة، ومكتوب فيها تم تسجيل الدخول عبر …. اختر أين تُفتح التذاكر.

  3. اختر الوجهة من القوائم:

    • Jira: الموقع (ينختار لك تلقائياً لو حساب Atlassian حقّك عليه موقع واحد بس)، وبعدها المشروع، وبعدها — لو تبغى — نوع التذكرة.
    • GitHub: المستودع.
    • Linear: الفريق.
  4. اضغط اختبر الاتصال، وبعدها ربط.

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

uMarker تصادق بتوكن أو مفتاح API تعطيه إيّاه (personal access token، أو مفتاح Linear، أو توكن Jira). اختر مزوّدك عشان تشوف وش ينطلب منك ومن وين تجيب الاعتماد:

الحقل القيمة
الاعتماد personal access token (classic أو fine-grained) بصلاحية إنشاء تذاكر في المستودع المطلوب. يُرسَل كـbearer token.
المستودع (repo) تختاره من قائمة المستودعات اللي يوصلها الرمز (وفيها بحث)، مثل acme/webapp.

التذاكر تُنشأ عبر POST https://api.github.com/repos/{owner}/{name}/issues (نسخة REST API رقم 2022-11-28). والتذكرة الراجعة مفتاحها #<number> ورابطها html_url.

و‏GitHub هو المزوّد الوحيد اللي ينقل كمان تسميات التقرير للتذكرة (شوف وش ينتقل للتذكرة).

اللوحة تمشّيك خطوة بخطوة، وبنفس الطريقة لكل مزوّد. وكل خطوة تحتاج الخدمة الثانية فيها رابط مباشر للصفحة بالضبط:

  1. من صفحة التكاملات بالحساب، اضغط ربط على بطاقة المتتبّع. تنفتح اللوحة على خطوات الربط.

  2. اتبع خطوات مزوّدك:

    • Jira: أنشئ رمز API في حساب Atlassian (الخطوة توديك لصفحة رموز API في Atlassian) والصقه. تأكّد من البريد (معبّى ببريدك أصلاً) واكتب اسم موقعك — acme يكفي. اضغط اعرض مشاريعي واختر المشروع، ونوع التذكرة لو تبغى.
    • GitHub: أنشئ رمزاً دقيق الصلاحيات (fine-grained) يوصل للمستودع مع صلاحية Issues للقراءة والكتابة (الخطوة توديك لصفحة الرمز الجديد في GitHub)، والصقه. وبعدها اختر المستودع من القائمة.
    • Linear: أنشئ مفتاح API شخصياً من إعدادات الأمان في Linear والصقه. وبعدها اختر الفريق من القائمة.
  3. اضغط اختبر الاتصال. uMarker تسوّي فحص دخول حقيقي على المتتبّع باللي قدامك على الشاشة بالضبط (نفس الفحص اللي تحت)، وما تحفظ شي. ولو نجح يظهر تم تسجيل الدخول باسم ومعه اللي وصله: موقع Jira حقّك، أو المستودع، أو Linear.

  4. اضغط ربط. يتفعّل بعد ما ينجح الاختبار؛ ولو غيّرت حقلاً بعد الاختبار، اللوحة تطلب تختبر مجدداً. وفيه احفظ دون اختبار ناجح لو احتجته. الاتصال ينحفظ active والاعتماد مشفّر عند التخزين.

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

الاتصال لحاله ما يفتح أي تذكرة. أرفقه بالمشاريع اللي المفروض تستخدمه:

  1. افتح المشروع وروح لتبويب التوزيع.

  2. أرفِق اتصال المتتبّع.

  3. اختيارياً اضبط هدفاً: مستودعاً أو فريق Linear أو مفتاح مشروع Jira ونوع تذكرة غير الافتراضي حقّ الاتصال. الشي الوحيد القابل للتجاوز هو الوجهة؛ أمّا الاعتماد والرابط الأساسي فيبقون على الاتصال. المسار يعني «وين في متتبّعك»، ما يعني أبداً «متتبّع مين».

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

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

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

المزوّد فحص الصحّة
GitHub GET /repos/{owner}/{name}: يتأكّد إن المستودع يوصل بالتوكن.
Linear استعلام GraphQL باسم viewer: يتأكّد إن المفتاح صالح.
Jira GET /rest/api/3/myself: يتأكّد إن البريد والتوكن يصادقون.

الفصل يحذف الاعتماد المحفوظ. ولو فيه مشاريع توجّه عبره، uMarker ترفض المحاولة الأولى وتسمّيها لك، عشان ما تسكت تذاكر أحد بلا تحذير. أكّد، وينحذف الاتصال ومساراته مع بعض.

والتذاكر المُنشأة سابقاً تبقى مرتبطة: روابط الرجوع على التقارير تظلّ سليمة وقابلة للنقر. اللي يتوقّف هو الإنشاء الجديد بس.

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

  1. افتح التقرير في صفحة التقرير.

  2. اضغط إنشاء تذكرة. uMarker تبني التذكرة من التقرير وترسلها للمتتبّع الموجَّه.

  3. مع النجاح، يعرض التقرير مفتاح التذكرة الجديدة كـرابط رجوع (مثل #142 أو ENG-142 أو MD-45) يفتح التذكرة الخارجية مباشرة.

حقل التقرير وين ينزل
العنوان عنوان GitHub/Linear، وملخّص Jira. الافتراضي: التعليق مقصوصاً على 80 محرف.
الوصف / النصّ نصّ التذكرة (وفي Jira بصيغة Atlassian Document Format). يحمل التعليق ورابط الصفحة ورابط لقطة موقّع ورابط اللوحة.
اللقطة رابط موقّع مضمّن بالنصّ، وما ينحطّ إلا لو كانت اللقطة لا تزال موجودة. وفي الباقة اللي لها نافذة احتفاظ وسائط، الرابط ينتهي معها؛ شوف تحت.
التسميات تسميات التقرير، على GitHub بس. تذاكر Linear وJira ما تستقبل تسميات.

والنصّ الافتراضي شكله كذا:

نصّ التذكرة
Reported via uMarker.
<the report's comment>
Page: https://site/checkout
Screenshot: https://api.umarker.com/… (link valid until 2027-01-12)
Open in uMarker: https://app.umarker.com/s/8f2c…/feedback/42

سطرا Page وScreenshot ما يظهرون إلا لمّا يكون للتقرير هذي القيم.

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

ولو رفض المتتبّع الطلب، ما ينحفظ شي ناقص (لا مفتاح ولا رابط)، ويقول التقرير للمُفرِز إن التذكرة ما انرفعت، وأي متتبّع رفض، وهل إعادة المحاولة تنفع ولا لا. أمّا سبب المزوّد بالضبط فينحفظ على الاتصال نفسه تحت التكاملات، ويقرأه المدير هناك كآخر خطأ للاتصال:

ردّ المتتبّع السبب المحفوظ على الاتصال
401 / 403 <Provider> rejected the credential — reconnect needed.
404 <Provider> destination not found — check your configuration.
429 <Provider> rate limit hit — try again shortly.
غيرها <Provider> returned HTTP <status>.

واختبار الاتصال لمّا يفشل يسجّل نفس السبب بنفس المكان، فيقدر المدير يعيد إنتاج المشكلة بلا ما ينتظر التقرير الجاي — أو، لو ما جاوب المتتبّع أصلاً، وش منعنا نوصله.

هذا مو ارتباطاً باتجاه واحد. وجّه webhook متتبّعك للرابط المعروض على الاتصال، وقفل التذكرة ينقل تقرير uMarker:

حدث المتتبّع التقرير يصير
تذكرة GitHub closed resolved، أو archived لو انقفلت كـnot planned
تذكرة GitHub reopened in_progress
حالة Linear completed / started / canceled resolved / in_progress / archived
فئة حالة Jira done / indeterminate resolved / in_progress

و‏Jira هي اللي تحتاج تقرأ صفّها مرّتين: هاتان الفئتان هما الوحيدتان اللي تربطهما uMarker، و‏Jira ما فيها فئة cancelled أصلاً. فلو كان سير عملك يحطّ «Cancelled» تحت فئة done، ترجع لك التذكرة resolved مو archived.

ورابط الـwebhook يحمل رمزاً خاصّاً بالاتصال، وما فيه شي في الحمولة يقرّر بيانات مين تنمسّ: الحساب ومجموعة المشاريع يجون من الاتصال، ويتحلّون على الخادم. أمّا من الحمولة نفسها فتقرأ uMarker شيئين: مفتاح التذكرة، وحالة المتتبّع لها. يعني اللي يمسك هذا الرابط يقدر ينقل التقارير المرتبطة بمشاريع ذاك الاتصال، ولا شي وراها. تعامل معه كسرّ: الرمز يُسَكّ وقت إنشاء الاتصال وما فيه زرّ تدوير له، فالطريقة الوحيدة لاستبدال رمز تسرّب هي إنك تفصل المتتبّع وتربطه من جديد — وهذا يحذف مسارات مشاريعه معه. والرمز المجهول يجيه 404؛ والحدث اللي ما تتصرّف عليه uMarker يُقبَل ويُتجاهَل، فما يدخل متتبّعك أبداً في عاصفة إعادة محاولات.

الإنشاء الناجح (غير المكرّر) يُطلق حدث issue_linked لكل وجهة يوجّه لها المشروع (سلاك، تيليجرام، Teams، أو webhook موقّع مشترك بالحدث)، ويرفع كمان إشعاراً داخل المنتج، فالتذكرة اللي تُفتح تلقائياً ما تصير بصمت. شوف Webhooks الصادرة للحمولة، والقنوات والتوجيه للاشتراك.

للمشغّلين: جهّز الربط بضغطة

Section titled “للمشغّلين: جهّز الربط بضغطة”

هذا الجزء لمن يشغّل منصّة uMarker نفسها، مو للمستأجرين. زرّ اربط عبر Jira / GitHub / Linear ما يطلع إلا بعد ما تسجّل تطبيق OAuth عند ذاك المزوّد وتفعّله من كونسول المشغّل. وقبلها، المستأجرين يربطون بالرمز، وما ينعرض لهم شي ميّت.

افتح التكاملات في كونسول المشغّل، ودوّر على تطبيقات OAuth — ربط بنقرة واحدة. كل مزوّد له رابط إعادة التوجيه للتسجيل (كما هو حرفياً) وجنبه زرّ نسخ؛ سجّل هذا الرابط عند المزوّد حرف بحرف. وشكله {APP_URL}/api/integrations/oauth/{provider}/callback.

  1. أنشئ تكامل OAuth 2.0 (3LO) من developer.atlassian.com/console/myapps.
  2. من Permissions، أضف Jira API وامنح الصلاحيات read:jira-work وwrite:jira-work وread:jira-user. أمّا offline_access فتطلبه uMarker وقت تسجيل الدخول عشان تقدر تجدّد الرمز.
  3. من Authorization، اختر OAuth 2.0 والصق رابط إعادة التوجيه كـcallback URL.
  4. من Distribution، خلّ التطبيق على Sharing. غير كذا ما يقدر يربط إلا حساب Atlassian حقّك أنت، وأي موقع ثاني ينرفض.
  5. من Settings، انسخ Client ID وSecret للكونسول.

وبعدها فعّل إتاحته للمستأجرين واحفظ. الصفّ يصير مُفعَّل — يظهر الزرّ للمستأجرين؛ والتطبيق المضبوط اللي ما انعرض يصير مضبوط، غير مُتاح، واللي ما له تطبيق غير مضبوط — بالرمز فقط. وسرّ العميل للكتابة فقط: اتركه فاضي بالحفظ اللي بعده عشان يبقى المحفوظ. وكل تغيير ينكتب بسجلّ التدقيق.