דלגו לתוכן

עזר ל-Control Center Connect

Control Center Connect מפעיל כניסות לספקים עבור שרתים שלא רשמו אפליקציות משלהם. שרת משתמש או ב-Connect המאוחסן של Control Center, או ב-Connect שהארגון שלו מפעיל (הפעלת שרת Connect), או באף אחד מהם. הבחירה נמצאת תחת הגדרות ← שרת ← כניסה מאוחדת ← Control Center Connect, בפקודה cc_server connect, או ב-CC_CONNECT_URL. סביבת עבודה עוקבת אחרי הבחירה הזו, אלא אם מנהל בחר אחרת לסביבה הזו תחת הגדרות ← סביבת עבודה ← אינטגרציות (בחירה לפי סביבת עבודה).

כל ספק הוא מסלול (lane). תחת שימוש באפליקציות שלי (או לפני שמישהו בוחר), מסלול רץ על האפליקציה של השרת עצמו כשהיא מוגדרת במלואה; אחרת הוא לא זמין. עם Control Center או Connect משלכם, Connect מריץ כל מסלול שהוא מציע: האפליקציות המשלו של השרת נשמרות אך אינן בשימוש, לא לכניסות, לא לאוטומציה של השרת ולא לסטטוס שהשרת מדווח. סביבת עבודה שבחרה בבחירה משלה מריצה במקום זאת כל מסלול לפי הבחירה הזו.

מסלול האפליקציה משלו צריכה דרך Connect
github App id, private key, client id ו-client secret אנשים נכנסים ל-GitHub App המשותף
google Client id ו-client secret אנשים מחברים את Google Calendar
linear Client id אנשים נכנסים ל-Linear
linear_app Client id מנהל סביבת עבודה מחבר את ה-actor של אפליקציית Linear
slack חיבור Slack משלו של סביבת העבודה מנהל סביבת עבודה מחבר את Slack לאפליקציית Slack המשותפת
klipy KLIPY_APP_KEY חיפוש GIF, שמועבר דרך Connect

אפליקציה משלו שמוגדרת רק בחלקה הופכת את המסלול שלה לשגיאה, ולעולם לא לנפילה שקטה אל Connect. סביבת עבודה תחת שימוש באפליקציות שלי לעולם אינה עוברת דרך אפליקציות השרת או דרך Connect, עבור אף ספק. שינוי בבחירת Connect של השרת אינו מנתק אף אחד מסביבת עבודה שבחרה בבחירה משלה.

מה Connect רואה ומה הוא לעולם לא רואה

קטע בשם “מה Connect רואה ומה הוא לעולם לא רואה”
Connect רואה Connect לעולם לא רואה
מזהה ההתקנה של השרת וחתימות הבקשות קוד מקור, תוכן מאגרים, diffs או טקסט של בקשות משיכה
חשבון הספק שנכנס, במהלך הכניסה כרטיסים, תמלולים או כל דבר במסד הנתונים של סביבת עבודה
לאיזו סביבת עבודה שייך פרטי גישה, כמזהה אטום בתוך האטם סודות האפליקציה של השרת עצמו: הם לעולם לא יוצאים מהשרת
המאגר שעבורו מונפק אסימון GitHub למאגר בודד אסימוני רענון במנוחה: הם קיימים רק בתוך אטמים שהשרת שומר
צוות Slack שקשור לשרת סודות Linear: השרת מחליף את הקוד של Linear בעצמו
מונחי חיפוש GIF, כשהוא מעביר את Klipy סיסמאות, מפתחות צימוד או מפתחות של ספקי מודלים
הפניות לאירועי Slack (צוות, ערוץ, מזהה הודעה) וטקסט של פקודות קו נטוי טקסט הודעות Slack: Connect משליך אותו עם ההגעה, והשרת קורא את ההודעה מ-Slack בעצמו

Connect שומר כניסות בתהליך, nonces ומטמונים לכל היותר 10 דקות, ומוני שימוש לשעה לכל היותר שעתיים. אסימון GitHub למאגר בודד שהונפק כאדם נשאר רשום, אטום לכניסה שביקשה אותו, עד שפג תוקפו (לכל היותר 8 שעות), כך ש-Connect יוכל להנפיק אותו שוב ולבטל אותו בעת ניתוק. הרשומות המתמשכות היחידות שלו הן קשרי Slack (לאיזה שרת כל צוות Slack קשור) ומזהי התקנה שנפרשו. שגיאות נושאות קוד בלבד, לעולם לא את התגובה של הספק. היומנים מתעדים מזהי התקנה רק כ-hash מפתוח, ואסימון GitHub רק כ-hashed_token שיומן הביקורת הארגוני של GitHub מציג עבורו, כך שבעל ארגון יוכל להתאים בין השניים.

מצב הגדרה התנהגות
לא מוגדר שרת חדש אף מסלול לא משתמש ב-Connect. ההכנה מבקשת מבעל השרת לבחור
hosted שימוש באפליקציות של Control Center https://connect.usectrl.dev, עם תצורה חתומה מחוץ לרשת. אפליקציות השרת המשלו אינן בשימוש
custom שימוש בשרת Connect מותאם Connect בכתובת HTTPS (http ב-loopback בלבד), שנחשב לאמין בשימוש הראשון. אפליקציות השרת המשלו אינן בשימוש
off שימוש באפליקציות שלי אף מסלול לא משתמש ב-Connect. רק אפליקציות משלו מכניסות אנשים

CC_CONNECT_URL בסביבה או ב-.env של השרת נועל את הבחירה: hosted, off, או כתובת Connect. אז ההגדרות מציגות את המנעול ואינן יכולות לשנות אותה.

הבנייה הזו אינה מקמפלת מפתח תצורה מאוחסן, ולכן מצב hosted מדווח hosted_unprovisioned ואינו מציע אף מסלול. אפליקציות משלו ו-Connect מותאם עובדים.

Connect המאוחסן פועל בקונטיינר יחיד. מפתח האטימה שלו ומפתח ה-GitHub App המשותף הם משתני סביבה שם, ולא מפתחות בכספת שרק חותמת או מפענחת, כפי ש-GitHub ממליצה למפתח פרטי של App. זה פער ידוע בתצורה הנוכחית.

שרת קורא את התצורה של Connect לכל היותר כל 10 דקות, ומחכה לכל קריאה 5 שניות לכל היותר. כש-Connect אינו נגיש, התצורה התקינה האחרונה ממשיכה לשמש וההגדרות מסמנות אותה כמיושנת.

הגדרות ← סביבת עבודה ← אינטגרציות ← Control Center Connect מחליף את בחירת השרת עבור סביבת עבודה אחת. כל חבר רואה אותה ואת המקום שבו עובר כל חיבור; רק מנהל סביבת העבודה משנה אותה.

בחירה התנהגות
כמו בשרת הזה ברירת המחדל. סביבת העבודה פועלת על מה שבעל השרת בחר; האפשרות מציינת את שמו
שימוש באפליקציות של Control Center Connect המאוחסן של Control Center, מה שלא יהיה בשימוש בשרת
שימוש באפליקציות שלי רק האפליקציות של סביבת העבודה: ה-GitHub App שלה, לקוח Google שלה, אפליקציית Linear שלה, מפתח Klipy שלה ואפליקציית Slack שלה. ספק בלי אפליקציה כזו כבוי כאן; אפליקציה חלקית היא שגיאת הגדרה
שימוש בשרת Connect מותאם Connect בכתובת HTTPS שסביבת העבודה מציינת. כתובות ברשת פרטית או מקומית נדחות
  • כל בחירה חוץ מכמו בשרת הזה שומרת את כניסות GitHub ו-Linear של כל אדם בחלל משלה של סביבת העבודה, כך שהן לעולם אינן מתערבבות עם הכניסות של כלל השרת
  • מעבר דורש אישור קודם: כולם בסביבת העבודה צריכים להיכנס מחדש ל-GitHub, ל-Linear ול-Google Calendar דרך האפליקציות החדשות
  • חיבור ה-Slack המשלו של סביבת העבודה פועל תחת כל בחירה; הוספת Control Center ל-Slack עוקבת אחר הבחירה
  • CC_CONNECT_URL נועל גם את סביבות העבודה כך שאין להן Connect משלהן: הן יכולות לעקוב אחרי השרת או להשתמש באפליקציות משלהן
  • Connect מותאם של סביבת עבודה נחשב לאמין בשימוש הראשון עבורה בלבד: לסמוך על האפליקציות החדשות שם לעולם אינו משנה את מה שהשרת או סביבת עבודה אחרת סומכים עליו
פריט מה הוא
מפתח התקנה seed של 32 בייטים בקובץ הסודות של השרת (connect_install_key), נפרד ממפתחות צימוד מכשירים
מפתח לכל Connect מפתח Ed25519 שנגזר מה-seed ומכתובת ה-Connect. כל בקשה ל-Connect נחתמת בו (RFC 9421)
מזהה התקנה 26 תווים הנגזרים ממפתח הציבורי. מוצג בהגדרות וב-cc_server connect status

לאותו שרת יש מזהה התקנה שונה לכל כתובת Connect. המזהה משתנה רק כאשר המפתח מוחלף.

כניסה דרך Connect מחזירה אטם פרטי גישה (credential seal): בלוב מוצפן שרק ה-Connect שיצר אותו יכול לפתוח. הוא קשור לספק, לכתובת ה-Connect, למזהה ההתקנה, לסביבת העבודה, לחשבון הספק, לאפליקציה ולדור הסוד.

  • השרת שומר את האטם ואת מזהה ההתקנה שעבורו נאטם. אסימוני הגישה נשארים בזיכרון
  • כדי לרענן, השרת שולח את האטם בחזרה ומקבל אסימון גישה חדש ואטם חדש
  • אטם שמזהה ההתקנה או כתובת ה-Connect שלו כבר אינם תואמים נמחק בקריאה הבאה שלו, והאדם נכנס מחדש. זה קורה לאחר החלפת מפתח, מעבר ל-Connect אחר, או תיקיית נתונים ששוחזרה על שרת אחר
  • אטם ש-Connect אינו יכול לפתוח נדחה עם access_denied

כל שרת יכול להשתמש בהתקנה של ה-GitHub App המשותף. Connect אינו שומר רשומה של השרת שרשאי להשתמש בה.

  • Install GitHub App תחת הגדרות ← סביבת עבודה ← אינטגרציות פותח את דף ההתקנה של האפליקציה ב-GitHub. השרת בונה את הקישור משם האפליקציה בתצורת Connect
  • אסימון למאגר בודד דורש שהאפליקציה תהיה מותקנת אצל הבעלים של המאגר, וגישה של האדם המחובר לאותו מאגר. זה האסימון של אותו אדם עצמו, מוגבל לתפקידו, ולעולם לא יותר
  • ארגון מגביל את Control Center ב-GitHub: על ידי הסרת ההתקנה, צמצום המאגרים שלה או הסרת האדם
  • לקריאות שרק האדם יכול לבצע, כמו הצגת ההתקנות שלו, Connect מעביר לשרת את אסימון המשתמש של ה-App של האדם עצמו, ולא אסימון למאגר בודד. כניסה בשרת היא אמון בשרת הזה עם האסימון הזה
  • ארגון שאוכף רשימת היתרים של כתובות IP ב-GitHub אינו יכול להשתמש ב-Connect המאוחסן, שכתובותיו אינן קבועות. במקום זאת הוא רושם GitHub App משלו, על השרתים שלו או על Connect שהוא מפעיל
  • ניתוק מבטל רק את הכניסה הזו: Connect מממש את אסימון הרענון שלו פעם אחת ומוחק את מה שחוזר ממנו, מוחק את אסימון המשתמש שלו ואת אסימוני המאגר הבודד ש-Connect הנפיק עבורו. עותק של האטם שלו שנשמר בכל מקום מפסיק לעבוד. הכניסות של האדם בשרתים ובסביבות עבודה אחרים ממשיכות לעבוד. כדי להסיר את Control Center מחשבון GitHub לגמרי, בטלו אותו ב-GitHub תחת הגדרות ← יישומים ← Authorized GitHub Apps ← בטל גישה

אסימונים שמונפקים כבוט ה-App (as: app) מציגים את אותו בוט ב-GitHub לכל שרת שמשתמש באותו Connect: GitHub אינה יכולה להבחין בין השרתים האלה.

  • כל שרת רשאי לתת לבוט לקרוא ולהגיב: read, review ו-comment (תגובות, תוויות, נמענים ותגובות רגשיות על issues ובקשות משיכה)
  • סקירת בקשת משיכה בשם הבוט (bot, שכותב בקשות משיכה) מותרת רק לשרתים שמפעיל Connect רשם ב-CONNECT_GITHUB_REVIEW_BOT_INSTALLS. כל שרת אחר מקבל תשובה needs_requester ומפרסם את הסקירה באסימון של האדם האחראי עצמו, ש-GitHub מצמצם לאותו אדם: הסקירה מופיעה בשמו. זה כולל פרסום סקירת AI, הערות סקירה ובקשות לסוקרים
  • דחיפה, יצירת ענף ופתיחת בקשת משיכה (write) לעולם אינן מונפקות כבוט המשותף. הן תמיד משתמשות בכניסה של מבקש הפעולה עצמו
  • אישור של בקשת משיכה אינו אוטומטי לעולם, בשום אסימון
  • שרת או סביבת עבודה עם GitHub App משלהם שומרים על הבוט לכל זה, כולל סקירות

מה בעלי ארגונים וחברים צריכים לדעת

קטע בשם “מה בעלי ארגונים וחברים צריכים לדעת”
  • שרת שאדם נכנס בו מחזיק את אסימון המשתמש ה-App שלו: עד 8 שעות לכל אסימון, מתחדש עד שהוא מתנתק. הוא יכול לפעול בשמו בכל מאגר שה-App המשותף מותקן עליו ושהוא יכול להגיע אליו. Connect יכול לנתק שרת לצמיתות (התקנה שנפרשה או נדחתה), אבל אסימון שכבר הונפק נשאר תקף עד שפג תוקפו
  • התקנת ה-GitHub App המשותף בארגון נותנת הסכמה לכל שרת Control Center שאיזה חבר נכנס בו, לא לשרת אחד בלבד
  • הבוט משותף, כאמור לעיל: ארגון לא יכול לדעת ב-GitHub איזה שרת פעל כבוט
  • ארגון שרוצה גבול משלו רושם GitHub App משלו ומפעיל Connect משלו (הפעלת שרת Connect), או מגדיר את ה-App על השרתים שלו
Connect איך השרת סומך על התצורה שלו
Hosted מאמת חתימת Ed25519 מול מפתחות שמקומפלים בבנייה. מסרב לתצורה עם epoch נמוך מהגבוה ביותר שראה (rollback)
Custom מצמיד את app id ו-client id של GitHub, את client ids של Google ו-Linear, ואת מזהי האפליקציה והלקוח של Slack בשימוש הראשון. שינוי משהה את הכניסות דרך Connect (pins_changed) עד שבעל השרת ילחץ על לסמוך על האפליקציות החדשות

הגדרות Connect של השרת זמינות לבעל השרת בלבד.

פעולה מה היא עושה
connect.status מצב, כתובת, נעילה, מזהה התקנה, בריאות, epoch של התצורה ומקור כל מסלול
connect.configure מגדירה hosted, custom (עם url) או off
connect.test שולפת שוב את התצורה ומדווחת על הבריאות
connect.confirmPins מקבלת את המזהים ששונו של Connect מותאם
connect.rotateKey מנפיקה מפתח התקנה חדש ומזהה התקנה חדש (force מחליף אותו גם כש-Connect לא הצליח לבטל את הישן); ראו החלפת מפתח ההתקנה

לסביבת עבודה יש בחירה משלה עם פעולות משלה, וכל אחת מהן מציינת את סביבת העבודה:

פעולה מי מה היא עושה
workspaceConnect.status כל חבר הבחירה, למה היא נפתרת, בריאות ומקור כל מסלול. מזהה ההתקנה והמזהים הממתינים מיועדים לאדמינים בלבד
workspaceConnect.set מנהל סביבת עבודה מגדירה inherit, hosted, custom (עם url) או own
workspaceConnect.test מנהל סביבת עבודה שולפת שוב את תצורת Connect של סביבת העבודה ומדווחת על הבריאות
workspaceConnect.confirmPins מנהל סביבת עבודה מקבלת את המזהים ששונו של Connect המותאם של סביבת העבודה

הכניסות עצמן משתמשות ב-oauth.lanes, oauth.begin, oauth.status, oauth.complete, oauth.connections ו-oauth.disconnect. האדם הוא תמיד מי שמחובר ומבצע את הקריאה.

  1. השרת מבקש מ-Connect להפעיל את המסלול, ומקבל את כתובת ה-authorize של הספק, שהוא בודק לפני שהוא מציג אותה. GitHub תמיד מציג את בורר החשבונות שלו
  2. האדם מאשר בדפדפן. הספק מחזיר אותו אל Connect
  3. Connect מציג מה השרת שהתחיל את הכניסה יוכל לעשות בשם האדם, ולכמה זמן. Connect אינו יכול לדעת מי מפעיל את השרת הזה, ולכן הדף מבקש מהאדם להמשיך רק אם הוא התחיל את הכניסה בעצמו, ולסגור אותו אם מישהו שלח לו את הקישור. כשהדפדפן נמצא ברשת אחרת מזו שממנה התחילה הכניסה, הדף אומר זאת: זה רגיל לשרת מאוחסן או למכשיר אחר, וזה גם מה שפישינג נראה כמו. ביטול מסיים את הכניסה: קוד הספק לעולם אינו נעשה בו שימוש. כל דף עונה פעם אחת: תשובה שלא הגיעה מהדף ש-Connect הציג זה עתה נדחית
  4. אחרי המשך, Connect מציג קוד בן 8 תווים וקישור control-center://oauth-done. מי שמקבל את הקוד מקבל את הגישה שרק אושרה, ולכן הוא נשלח רק למקום שבו הכניסה התחילה
  5. האדם מקליד את הקוד באפליקציה, או פותח את הקישור. השרת מממש את הכניסה עם הקוד וההוכחה שלו לבקשה

כניסה פוקעת אחרי 10 דקות. חמישה קודים שגויים מסיימים אותה. קישור שהאפליקציה הזו לא התחילה נדחה עם הכניסה לא התחילה כאן. Connect מגביל כמה כניסות כתובת רשת אחת יכולה להתחיל, וכמה פעמים מונפקים אסימוני GitHub לכל אדם ושרת, לכל אדם בין שרתים, לכל כתובת ולכל האפליקציה. לכניסות חדשות יש תקציב משלהן, כך שהן לעולם אינן מעכבות את החידושים שאחרים צריכים. מעבר למגבלה, קריאה נדחית עם rate_limited, והשרת מנסה שוב מאוחר יותר בלי לנתק אף אחד. כניסה שחורגת ממגבלת האדם מבוטלת ב-GitHub ונדחית.

רק בעל השרת יכול להחליף את המפתח, עם החלפת מפתח בכרטיס Control Center Connect תחת הגדרות ← שרת ← כניסה מאוחדת. אין לכך פקודה. ההחלפה:

  • מנתקת את כל האנשים מכל מסלול שרץ דרך Connect. לכל שרת Connect שבו נעשה שימוש במפתח הישן, השרת מבטל מתוכו את הכניסות ל-GitHub ול-Slack שהוא מחזיק (לכניסת Google אין מה לבטל והיא פשוט פוקעת)
  • פורש את מזהה ההתקנה הישן בכל אחד משרתי ה-Connect האלה, חתום במפתח הישן ומוכח באטם פרטי גישה אחד שהשרת מחזיק מאותו Connect. מאותו רגע Connect דוחה כל בקשה שנעשתה עם המפתח הישן, כך שאטם או עותק של המפתח הישן שנלקחו מהשרת הזה חסרי תועלת, ומרחבי Slack שקשורים למזהה הישן משתחררים כדי שיוכלו להתחבר שוב. אסימונים שכבר הונפקו נשארים תקפים עד שפגים (שעה לאסימון בוט, שמונה שעות לאסימון של אדם). שרת Connect שאין לשרת הזה אטם ממנו אינו מכיל מה לפרוש, והוא מדולג
  • אחר כך נותן לשרת מפתח התקנה חדש ומזהה התקנה חדש
  • אם שרת Connect אינו נגיש, או מסרב לפרוש את המזהה הישן, עוצר לפני שמחליפים מפתחות ומציג Connect לא הצליח לבטל את המפתח הישן. החלפה בכל זאת מחליפה מפתחות בכל מקרה; מזהה ההתקנה הישן נשאר אז שמיש ב-Connect הזה עד שפגים האסימונים שלו, לכל היותר 8 שעות ל-GitHub
  • משאיר את הכניסות דרך האפליקציות של השרת עצמו ללא שינוי
  • דורש הוספת מזהה ההתקנה החדש לרשימת ההיתרים של Connect מותאם
קוד משמעות
hosted_unprovisioned לבנייה הזו אין מפתח תצורה מאוחסן
signature התצורה המאוחסנת נכשלה בבדיקת החתימה שלה
rollback Connect הגיש תצורה ישנה מזו שהשרת כבר ראה
unreachable השרת לא יכול להגיע ל-Connect
install_blocked Connect לא מתיר את מזהה ההתקנה הזה, או שהוא נפרש
pins_changed Connect מותאם הכריז על מזהי אפליקציה שונים
protocol Connect ענה בצורה שהשרת הזה אינו מבין