יצירת GitHub App

מדריך זה מראה כיצד להעניק לשרת שלכם זהות GitHub משלו. זה לוקח כשתי דקות, רק בעל השרת עושה זאת, וזה צריך לקרות פעם אחת בלבד לכל שרת.

לחיבור החשבון שלכם לאחר מכן, ראו הגדרת אינטגרציית GitHub.

מדוע השרת שלכם זקוק לאפליקציה משלו

שני תפקידים שונים נולדים מרישום אחד, והאפליקציה היא מה שהופך את שניהם לאמינים:

תפקיד	מה עונה לו	מדוע זה חשוב
אדם נכנס	מזהה הלקוח של האפליקציה, דרך זרימת התקן	אתם מקבלים פרטי גישה שהם שלכם, על השרת, בכל מכשיר — בלי אסימון להדביק או להחליף
השרת פועל	המזהה של האפליקציה + מפתח פרטי ← אסימון התקנה	webhooks, סריקת בקשות משיכה וסנכרון כרטיסים מפסיקים להיות תלויים בכך שהאסימון של אדם אחד עוד בתוקף

שימו לב למה שאינו מופיע בטבלה הזו: סוד לקוח. זרימת התקן של GitHub מזדהה באמצעות מזהה הלקוח בלבד — גם בקשת קוד התקן וגם בקשת האסימון החוזרת — כך שאין סוד שצריך לשמור לשם הכניסה.

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

דרישות מקדימות

אתם בעל השרת — פעולות providerApps.* מותרות רק לו, והכרטיס אינו נראה לכל השאר
חשבון GitHub, או ארגון שאתם יכולים ליצור בו אפליקציות
שום דבר שנגיש לציבור: הכניסה היא זרימת התקן, כך שהשרת אינו זקוק לפורט נכנס, מנהרה, כתובת URL ל-callback או דומיין

רישום האפליקציה

עברו אל github.com/settings/apps/new (עבור ארגון: Settings → Developer settings → GitHub Apps → New GitHub App)
GitHub App name — כל דבר; Control Center (yourname) מתאים. השם יופיע בקומיטים ובהערות שהשרת יוצר
Homepage URL — כל דבר, למשל https://github.com/your-name
Callback URL — השאירו ריק. לזרימת התקן אין כזו
סמנו Enable Device Flow. זו ההגדרה היחידה שבלעדיה הכניסה אינה יכולה לעבוד
הסירו את הסימון מ-Webhook → Active, אלא אם אתם מחברים webhooks בנפרד
תחת Repository permissions, העניקו לפחות:
- Contents: Read and write
- Metadata: Read-only (חובה)
- Pull requests: Read and write
- Issues: Read and write, אם אתם משתמשים ב-GitHub Issues לכרטיסים, ולחיפוש ההערות של הבוט בשיחות בקשות משיכה (ראו דיבור עם Control Center מבקשת משיכה ב־GitHub)
- Checks: Read-only, עבור מצב ה-CI בעמוד בקשת המשיכה
תחת Where can this GitHub App be installed?, בחרו מה שמתאים — “Only on this account” נכון לשרת אישי
לחצו על Create GitHub App

איסוף שלושת הערכים

בעמוד האפליקציה, מיד לאחר היצירה:

ערך	היכן
App ID	לשונית General, סמוך לראש
Client ID	לשונית General, תחת “Client secrets”
Private key	Generate a private key — קובץ `.pem` יורד

קובץ המפתח הפרטי יורד פעם אחת, ו-GitHub לא יציג אותו שוב לעולם. שמרו אותו עד שהדבקתם אותו; תמיד אפשר ליצור אחר.

סוד לקוח הוא אופציונלי וקונה בדיוק דבר אחד: אם תשאירו את “Expire user authorization tokens” דלוק, הוא מה שמחדש בשקט את האסימון של האדם במקום לבקש ממנו להיכנס מחדש כל שמונה שעות. הכניסה עצמה לעולם אינה משתמשת בו.

ההגדרה הפשוטה יותר היא לכבות את התפוגה, ואז אין צורך בסוד בשום מקום. אם תשאירו אותה דלוקה, צרו סוד והדביקו אותו בהגדרות ← שרת ← כניסה מאוחדת (הכרטיס אפליקציות ספק) — אין משתנה סביבה עבורו, ואף אחד אינו מוטמע בבנייה, כך שהוא נשאר על השרת שלכם.

התקנת האפליקציה בחשבון שלכם

אפליקציה שנרשמה אך אינה מותקנת יכולה לאמת אנשים, אך לא לקרוא דבר.

בעמוד האפליקציה, פתחו את Install App
התקינו אותה בחשבון או בארגון שלכם
בחרו All repositories, או בחרו את המאגרים שהשרת הזה אמור לראות

הדבקה ב-Control Center

עברו אל הגדרות ← שרת ← כניסה מאוחדת וגללו אל הכרטיס אפליקציות ספק
בבלוק GitHub, הגדירו כל שדה:
- מזהה אפליקציה — ה-App ID המספרי
- מפתח פרטי — הדביקו את כל קובץ ה-.pem, כולל שורות ה-BEGIN וה-END
- מזהה לקוח — מאותו עמוד
- סוד לקוח — רק אם יצרתם אחד (לחידוש האסימון)
לחצו על בדוק

המפתח מנותח בזמן השמירה, כך שהדבקה קטועה או בפורמט שגוי נדחית מיד ולא נכשלת בבקשת רקע שעות מאוחר יותר. בדוק מרחיק לכת ושואל את GitHub על אילו חשבונות האפליקציה מותקנת — “נשמר” ו“עובד” הן שתי טענות שונות, ורק השנייה אומרת שמשהו ירוץ.

נקודת ביקורת: בלוק GitHub מציג “השרת יכול לפעול בשם עצמו, ואנשים יכולים להיכנס”, והשורה GitHub תחת הגדרות ← סביבת עבודה ← פרופיל וזהות ← אחסון קוד מציעה כעת כניסה עם GitHub.

הגדרה באמצעות משתני סביבה במקום זאת

להתקנה ללא ממשק או מתוסרטת, השרת מזריע כל שדה מהסביבה בפעם הראשונה שאין לו ערך שמור:

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="$(cat control-center.private-key.pem)"
GITHUB_CLIENT_ID=Iv1.0123456789abcdef

אין דגלי שורת פקודה עבור אלה — סוד בשורת פקודה קריא לכל תהליך במארח דרך ps. הסביבה היא המקום היחיד להגדיר אותם, והיא גוברת על כל מה שהבנייה מספקת. .env.template הוא הרשימה המלאה.

לפיתוח מקומי, ה-.env בשורש המאגר נושא את אותם ערכים, ושולחן העבודה מעביר אותם לשרת שהוא מפעיל. שימו את המפתח על שורה אחת שם: ערך ב-.env הוא שורה אחת, ו-\n בתוך מרכאות כפולות מפוענח לשורה חדשה.

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEow…\n-----END RSA PRIVATE KEY-----"

GITHUB_APP_ID ו-GITHUB_APP_PRIVATE_KEY הם אותם שמות שמתווך האסימונים של ארגז החול כבר קורא, כך שמארח שהגדיר אסימוני סוכן מפורטים מקבל את מסלול הכניסה בחינם. ההזרעה מתרחשת פעם אחת לכל שדה — לאחר מכן הערך השמור גובר, כך שעריכה בהגדרות אינה מתבטלת בהפעלה מחדש הבאה.

עשו את אותו הדבר עבור Linear

ל-Linear אין זרימת התקן, ולכן הכניסה שלו היא סבב בדפדפן והוא כן זקוק לכתובת URL ל-callback — הכרטיס אפליקציות ספק מציג לכם את הכתובת המדויקת לרישום.

צרו אפליקציית OAuth ב- linear.app/settings/api/applications/new
הגדירו את כתובת URL ל-callback לכתובת שהכרטיס מציג, כלשונה
הדביקו את מזהה הלקוח ואת סוד הלקוח בבלוק Linear
אפשר להוסיף מפתח API של סביבת עבודה — זהו פרט הגישה שהשרת משתמש בו לסנכרון כרטיסים כשאף אדם לא ביקש

פתרון תקלות

תיבת הדו-שיח של הכניסה אומרת שהספק לא החזיר קוד התקן

Enable Device Flow כבוי באפליקציה. הפעילו אותו תחת General ונסו שוב.

הבדיקה אומרת שפרטי הגישה עובדים, אבל האפליקציה אינה מותקנת בשום מקום

רישום והתקנה הם שני שלבים נפרדים. פתחו את Install App בעמוד האפליקציה והתקינו אותה.

הבדיקה אומרת שלא ניתן היה לקרוא את המפתח הפרטי

הדביקו את כל קובץ ה-.pem, כולל השורות -----BEGIN ו------END. לא ניתן להשתמש במפתח ed25519 או EC — GitHub Apps חותמות עם RSA.

חבר נכנס אבל אינו רואה מאגרים

האפליקציה אינה מותקנת בחשבון שמחזיק בהם, או שההתקנה שלה בוחרת מאגרים אחרים. הכניסה האישית שלהם מעניקה רק את מה שהאפליקציה מורשית לראות.