דפדפן קוד (Code Browser)

ייבוא ריפו חדש

כדי לייבא ריפוזיטורי חדש לדפדפן הקוד, יש להריץ את הפקודה הבאה (אפשר להריץ ב-Shell של Render):

python3 - <<'PY'
from services.repo_sync_service import initial_import
from database.db_manager import get_db

res = initial_import("<קישור לריפו.git>", "שם הריפו", get_db())
print(res)
PY

הערה

יש להחליף את <קישור לריפו.git> בכתובת ה-Git של הריפו (למשל https://github.com/user/repo.git) ואת "שם הריפו" בשם שיוצג בממשק.

הגדרת סנכרון אוטומטי

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

הגדרת Webhook ב-GitHub

  1. כנסו לריפו ב-GitHub

  2. לכו ל-Settings → Webhooks → Add webhook

  3. מלאו את הפרטים הבאים:

    שדה

    ערך

    Payload URL

    https://<הדומיין של ה-וובאפפ>/api/webhooks/github

    Content type

    application/json

    Secret

    אותו ערך שמוגדר ב-GITHUB_WEBHOOK_SECRET בסביבה שלכם

    Events

    בחרו Just the push event. בריפו של CodeBot עצמו בחרו Let me select individual events, וסמנו גם את deployment_status לצד push: הוא מפעיל את אינדקס התיעוד אחרי כל פריסה של האתר (אינדקס התיעוד)

  4. לחצו Add webhook

אזהרה

ודאו שה-Secret תואם בדיוק לערך שמוגדר ב-GITHUB_WEBHOOK_SECRET בשרת. אם הערכים לא תואמים, ה-Webhook ייכשל עם שגיאת אימות.

בדיקת הגדרת ה-Webhook

לאחר הגדרת ה-Webhook:

  1. בצעו git push לריפו

  2. כנסו ל-Settings → Webhooks ב-GitHub ובדקו את סטטוס המשלוח האחרון

  3. סטטוס 200 מעיד על הצלחה

  4. ודאו שהקבצים עודכנו בדפדפן הקוד

מה קורה לג’וב סנכרון

כל push לענף הראשי נכנס לתור (sync_jobs במונגו), וה-worker של הוובאפ מריץ אותו (_run_sync_logic ב-services/repo_sync_service.py). הסטטוס הסופי של הג’וב נקבע לפי התוצאה (_job_status_for באותו קובץ):

  • completed — הקבצים סונכרנו, או שלא היה מה לסנכרן.

  • failed — הסנכרון היה צריך לרוץ ולא רץ. ה-error של הג’וב הוא הסיבה (FAIL_*): אין mirror בדיסק של השירות, ה-fetch נכשל, אין לריפו last_synced_sha, רשימת השינויים לא התקבלה, last_synced_sha זז באמצע כי סנכרון אחר רץ באותו זמן, או abandoned — ה-worker שהריץ אותו הפסיק לסמן שהוא חי (למטה). התוצאה המלאה נשמרת ב-result. עד אוקטובר 2026 ארבעת הראשונים סומנו completed.

  • skipped — push לריפו שאין לו רשומה ב-repo_metadata: הוא הוסר, וה-webhook שלו נשאר מוגדר ב-GitHub.

הבסיס של ההבדלים הוא ``last_synced_sha`` שבמסד, ולא ה-SHA הקודם שה-webhook שולח. last_synced_sha הוא מה שבאמת נכנס לאינדקס, ולכן סנכרון שמצליח משלים גם את השינויים של ג’ובים שנכשלו לפניו, בלי ניסיון חוזר. ניסיון חוזר של ג’וב ישן הוא דווקא מה שאסור: אחרי שסנכרון חדש יותר כבר רץ, הוא היה מחזיר קבצים לגרסה ישנה. עד אוקטובר 2026 הבסיס היה ה-SHA מה-webhook, ולכן השינויים של push שהסנכרון שלו נכשל לא נכנסו לאינדקס לעולם: ה-push הבא התחיל מה-SHA שאחריו. last_synced_sha מתעדכן רק אם הוא עדיין הבסיס שהסנכרון התחיל ממנו. השינויים שלא נכנסו מגיעים בסנכרון המוצלח הבא, כלומר עם ה-push הבא לריפו.

לכל ריפו רץ ג’וב אחד בכל רגע, והמסד אוכף את זה. אינדקס ייחודי חלקי על repo_name, רק על ג’ובים ב-running (SYNC_JOBS_ONE_RUNNING_INDEX ב-services/repo_sync_service.py). ה-worker מדלג על ריפו שיש לו ג’וב רץ, ותופס במקומו את הג’וב הוותיק של ריפו אחר; בתוך ריפו הסדר נשמר. שני workers שתופסים באותו רגע ג’ובים של אותו ריפו — כמה תהליכי gunicorn, או שני שירותים על אותו מסד — נעצרים במסד: השני מקבל DuplicateKeyError, הג’וב שלו נשאר pending, והוא מנסה בסבב הבא. עד אוקטובר 2026 שני ג’ובים של אותו ריפו יכלו לרוץ יחד, ו-base_moved רק גילה את זה בדיעבד.

ג’וב שה-worker שלו מת משתחרר. בזמן ג’וב, חוט קטן מעדכן heartbeat_at כל SYNC_JOB_HEARTBEAT_SECONDS. ג’וב ב-running שלא עודכן SYNC_JOB_STALE_SECONDS (ובלי heartbeat_at, לפי started_at) מסומן failed עם abandoned, והריפו משתחרר. לרוב זה תהליך שנהרג באמצע, למשל בפריסה. הג’וב לא חוזר לתור: הסנכרון הבא משלים את מה שהוא פספס, כי הבסיס הוא last_synced_sha. ג’וב שבכל זאת מסתיים אחרי השחרור כותב את התוצאה האמיתית שלו מעל הסימון. הדופק מוכיח שהתהליך חי, לא שהג’וב מתקדם, ולכן ג’וב תקוע בתוך תהליך חי ממשיך להחזיק את הריפו. כל הקבועים באותו קובץ.

האינדקסים של sync_jobs נוצרים כשה-worker עולה (ensure_sync_jobs_indexes), לפני התפיסה הראשונה: אינדקס לתפיסה, ה-TTL שמוחק ג’וב כשמגיע ה-expire_at שנקבע לו ביצירה (trigger_sync), והייחודי. לפני הייחודי משחררים ג’ובים שה-worker שלהם מת וסופרים ריפואים עם יותר מג’וב רץ אחד. כשיש כאלה האינדקס לא נוצר. TTL או ייחודי שאינם במקום נשלחים כאירוע db_sync_jobs_index_missing (קטלוג אירועים קנוניים). עד אוקטובר 2026 שני הראשונים הוגדרו רק ב-scripts/create_repo_indexes.py, שמעכשיו קורא לאותה פונקציה.

ה-worker עולה עם שרת הוובאפ (start_webapp_repo_threads, בעליית webapp/app.py), אחרי המילוי שהוא מחכה לו (דיסק בלי mirrors: המילוי בעלייה), ולא רק כשמגיע webhook. כך ג’ובים שנשארו pending מלפני פריסה, ג’ובים שנוצרו בשירות שה-worker שלו כבוי, ושחרור ג’ובים שה-worker שלהם מת, לא מחכים ל-webhook הבא שמגיע לשירות הזה. עד אוקטובר 2026 ה-worker עלה רק ב-trigger_sync, כלומר בתהליך שקיבל webhook.

כיבוי ה-worker בשירות: WEBAPP_SYNC_WORKER=0. ה-worker לא עולה, לא בעלייה ולא עם webhook. הג’ובים, גם אלה שהשירות הזה יוצר מה-webhook, נשארים pending עד ששירות אחר על אותו מסד תופס אותם. זה לזמן מעבר בין שני שירותים: כל ג’וב מעדכן רק את הדיסק של השירות שתפס אותו, ולכן בשירות שיוצא מכבים את ה-worker, וכל הג’ובים עוברים לשירות החדש.

דיסק בלי mirrors: המילוי בעלייה

שירות וובאפ שעולה ובדיסק שלו חסרים mirrors משכפל לבד כל ריפו שיש לו רשומה ב-repo_metadata. זה המצב אחרי מעבר לשירות חדש, או אחרי שהדיסק נמחק. בלי המילוי דפדפן הקוד לא מוצא את הריפואים, וכל ג’וב סנכרון נכשל עם mirror_missing (מה קורה לג’וב סנכרון) עד ייבוא ידני של כל ריפו מחדש. את המילוי עושה start_mirror_fill ב-services/repo_sync_service.py, בחוט רקע בשם repo-mirror-fill. הוא עולה רק בתהליך השרת של הוובאפ (_is_webapp_runtime ב-webapp/app.py), כמו מתזמן הגיבויים.

  • מה הוא עושה: קורא את הרשומות מה-primary, ולכל ריפו בלי mirror בדיסק מריץ init_mirror, שהוא git clone --mirror מה-repo_url שברשומה. ריפו פרטי צריך את GITHUB_TOKENS או GITHUB_TOKEN בשירות (אימות מול GitHub — הטוקן לא נשמר במראה).

  • מה הוא לא עושה: לא כותב למסד, ולא מריץ את הייבוא (initial_import). הייבוא דורס את last_synced_sha, את repo_url ואת default_branch בערכים מה-mirror, ומאנדקס את כל הריפו מחדש, ואילו האינדקס במונגו כבר קיים. המילוי גם לא מושך mirror שכבר קיים, ולא מוחק mirror שאין לו רשומה. את המשיכה עושה ג’וב הסנכרון, ואת ההסרה unmirror_repo.

  • ה-worker של הסנכרון מחכה לו. ה-worker לא תופס ג’וב לפני שהמעבר הראשון של המילוי בתהליך שלו הסתיים, ומחכה עד MIRROR_FILL_WAIT_SECONDS. לניסיונות החוזרים הוא לא מחכה. אחרי הזמן הזה הוא מתחיל בכל מקרה ורושם WARNING, וג’וב של ריפו שה-mirror שלו עוד לא בדיסק נכשל עם mirror_missing. ג’וב שמחכה לא מאבד כלום: הוא נשאר pending במונגו.

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

  • כמה workers של gunicorn: רק תהליך אחד ממלא, תחת נעילת flock. השאר מחכים לו, ואז מוצאים את הכול קיים.

  • בלוג: repo mirror fill started בעלייה, ו-repo mirror fill finished in ... עם הספירות בסוף. cloned הוא מספר הריפואים ששוכפלו, errors מספר הכשלים, ו-retry_repos הריפואים שהכשל שלהם ינוסה שוב. כשיש כשלים השורה היא WARNING, ולכל כשל יש גם שורה משלו.

  • ניסיונות חוזרים. מעבר שנכשל על תקלה שעשויה לחלוף מנוסה שוב: המסד עוד לא זמין (get_db מחזיר None, או שגיאת חיבור של מונגו), או ששכפול של ריפו נכשל. ההמתנה לפני כל ניסיון מוכפלת, מ-_MIRROR_FILL_RETRY_BASE_SECONDS ועד _MIRROR_FILL_RETRY_CAP_SECONDS, ויש עד MIRROR_FILL_MAX_ATTEMPTS מעברים בסך הכול. כל הקבועים ב-services/repo_sync_service.py, ויחד זה בערך שעה. כל מעבר קורא מחדש את הרשומות ומשכפל רק את מה שעוד חסר. כשהניסיון ה-MIRROR_FILL_ALERT_ATTEMPT נכשל, נשלחת פעם אחת התראה לבוט, repo_mirror_fill_failing (מילוי ה-mirrors בעליית הוובאפ). אחרי הניסיון האחרון נרשם ERROR, repo mirror fill gave up, והריפו נשאר חסר עד העלייה הבאה או עד ייבוא מחדש. חריגה לא צפויה, כמו באג או תיקייה שאי אפשר ליצור, לא מנוסה שוב, ונרשמת פעם אחת עם traceback.

  • כיבוי: WEBAPP_REPO_AUTOFILL=0.

החלק שמשותף לשירות ה-MCP, שממלא את הדיסק שלו באותה דרך בכל מעבר של ה-autosync (רענון אוטומטי (autosync)), נמצא ב-services/repo_mirror_fill.py.

משתני סביבה נדרשים

משתנה

תיאור

GITHUB_WEBHOOK_SECRET

הסוד המשותף לאימות Webhooks מ-GitHub

תצוגה מרונדרת (Markdown ועמודי תיעוד)

קובץ .md בדפדפן הקוד אפשר לראות מרונדר, בכפתור ”תצוגת Markdown“ שבראש הקובץ. אותו כפתור מציג מרונדר גם עמוד rst של אתר התיעוד, מהבנייה של האתר (עמודי התיעוד (rst)). הרינדור הוא MarkdownLiveRenderer (webapp/static/js/live-preview.js), ואותו רינדור משמש גם את כרטיסי החיפוש בתיעוד בעמוד הקבצים (תיעוד).

  • הספריות מגיעות מהבאנדל המקומי, בכוונה. webapp/static/js/markdown-deps.js טוען ישירות את md_preview.bundle.js, ולא את markdown-it ו-highlight.js מ-CDN. markdown-it מ-CDN מגיע בלי התוספים, והתצוגה הייתה מאבדת הערות ותרשימים בלי שום שגיאה. הבאנדל גדול, ולכן הוא נטען רק כשצריך אותו, ואחר כך מגיע מהמטמון עד שהגרסה משתנה.

  • הכתובת של הבאנדל נגזרת מהתגית של הטוען: אותה תיקייה ואותו ?v=. כך עדכון של הבאנדל מגיע לדפדפן יחד עם הקוד שטוען אותו, גם אחרי שנה במטמון. אין כתובת בלי גרסה כגיבוי.

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

  • העיצוב יושב ב-webapp/static/css/markdown-preview.css, שדפדפן הקוד וכרטיסי החיפוש בתיעוד טוענים. הגבולות וההדגשה נקראים בו דרך טוקנים של הרכיב ולא ישירות מהפלטה של דפדפן הקוד, כי עמוד הקבצים לא טוען אותה — הכלל ב-מערכת ערכות הנושא והטוקנים החדשה. ווי הדריסה של ערכות מיובאות לבלוקי הקוד מתוארים ב-בלוקי הקוד בתצוגת ה-Markdown של דפדפן הריפו.

עמודי התיעוד (rst)

קובץ rst של אתר התיעוד מוצג מרונדר באותה תצוגה, באותו רינדור ובאותו עיצוב כמו קובץ Markdown. ההבדל הוא רק מאיפה בא המארקדאון: מקובץ Markdown — מהתוכן שלו; מקובץ rst — מהעמוד שלו באינדקס של התיעוד (renderPreview ב-webapp/static/js/repo-browser.js).

  • מאיפה העמוד. אין בוובאפ ממיר rst. העמוד הוא הסעיפים של אותו עמוד בקובץ הייצוא של האתר, לפי הסדר, כל אחד עם הכותרת שלו ברמה שלו (page_markdown ב-services/docs_index_service.py). את הקובץ כותבת בניית האתר בממיר של כפתור ”העתק תוכן הדף“ (Doc Authoring Guide (Sphinx/RTD)), כלומר ההמרה היא של Sphinx: הפניות, הערות, טבלאות ותרשימי mermaid מגיעים כמו באתר. מעבר האינדוקס שומר את העמוד באוסף docs_pages, אחרי כל פריסה של האתר (אינדקס התיעוד).

  • קישורים ותמונות. קישור בעמוד הוא כתובת מלאה באתר התיעוד, גם קישור לסעיף באותו עמוד, ותמונה מוצגת כתמונה, מהכתובת שלה באתר. כך הייצוא בונה אותם (scripts/docs_export_sections.py), וה-CSP של הוובאפ (_add_default_csp ב-webapp/app.py) מתיר תמונות מכל כתובת https.

  • למי מוצע. רק לקובץ rst בריפו שממנו האתר נבנה (offers_docs_page ב-services/docs_page_view.py), ורק כשיש לו עמוד באינדקס: /repo/api/file מחזיר has_docs_page, ובלעדיו הכפתור לא מוצג. עמודי docs/api/ אינם בקובץ הייצוא, ולכן הם מוצגים כקוד בלבד. כשל מסד בבדיקה הזו מציג את הקובץ כקוד, ונרשם בלוג.

  • כשהקובץ חדש מהעמוד. אחרי מיזוג המראה מתעדכנת עם ה-push, והאתר נבנה ונפרס רק אחר כך — ובינתיים העמוד הוא של הבנייה הקודמת. /repo/api/docs-page/<path> מחזיר לכן freshness: הוא משווה את התוכן (ה-blob, ב-get_blob_ids של המראה, פקודת git ls-tree אחת לכל קומיט) בקומיט שהאינדקס נכון אליו (indexed_source_commit) מול הקומיט האחרון שהמראה סונכרנה אליו (last_synced_sha ב-repo_metadata; בגרסה מההיסטוריה — מול הגרסה שנבחרה) — של הקובץ, ושל כל קובץ אחר שהעמוד נבנה ממנו: קוד ש-literalinclude מציג (docs/conversation-handlers.rst מציג קוד מ-handlers/save_flow.py), קובץ ש-include משלב, תמונה, ומודול ש-autodoc מתעד. את הרשימה הזו רושם Sphinx עצמו בבנייה, והיא נשמרת עם העמוד (dependencies, Doc Authoring Guide (Sphinx/RTD)). ההשוואה היא לקומיט שסונכרן ולא ל-commit_sha של הקובץ ב-repo_files, כי הסנכרון מעדכן את commit_sha רק לקבצים שהשתנו: אחרי קומיט שמשנה רק את handlers/save_flow.py, קובץ ה-rst עדיין מצביע על קומיט ישן, ושם הקוד עוד לא השתנה. קומיט שלא נגע בהם אינו שינוי. כשהקובץ עצמו השתנה, מעל העמוד מופיעה השורה ”התצוגה מהבנייה האחרונה של אתר התיעוד; הקובץ השתנה מאז“. כשרק קובץ אחר שהעמוד נבנה ממנו השתנה (או נמחק), השורה אומרת שקובץ כזה השתנה, ונוקבת בו (changed_dependencies בתשובה). כשאין עם מה להשוות — מעבר באמצע, אינדקס שנבנה בכללים בלי עמודים (RECORDS_VERSION), ריפו בלי קומיט מסונכרן, או קומיט שהמראה עוד לא משכה — מופיעה שורה שאומרת שכרגע אי אפשר לבדוק. מה שלא נבדק הוא שינוי בממיר או בתצורה של האתר עצמו (docs/_static/copy-page.js, docs/conf.py): הוא חל על כל העמודים ואינו קלט של עמוד אחד, וגם Sphinx אינו רושם אותו כתלות של עמוד. הנוסחים ב-DOCS_PAGE_NOTES, והמצבים ב-FRESHNESS_* ב-services/docs_page_view.py.

  • גרסה מההיסטוריה. כשבוחרים בהיסטוריה גרסה קודמת של הקובץ, העמוד מושווה אליה ולא לגרסה הנוכחית. העמוד עצמו נשאר של הבנייה האחרונה: לגרסאות קודמות אין עמוד.

התוכן כמו שהוא בריפו, ומי רואה אותו

הקובץ מוצג תו בתו כמו שהוא במראה. /repo/api/file/<path> קורא אותו ב-get_file_content, כלומר git show דרך _run_git_command (services/git_mirror_service.py), והפלט חוזר בלי שינוי. אותו תוכן ממלא את טופס ההעלאה ב“ערוך / העתק“ (/upload/from-repo), חוץ מ-CR: השרת שולח אותו ב-HTML כמו שהוא, אבל ערך של textarea לא מחזיק CR, ולכן בקובץ עם CRLF או CR בודד הטופס מחזיק LF — מגבלה של HTML (ניקוי קוד מודבק (Pasted-code cleanup)). ואותו תוכן האינדקס של הריפו (repo_files) קורא כשהוא מחשב size ו-lines. ”תו בתו“ כולל את סופי השורות: _run_git_command קורא את הפלט כבתים ומפענח אותו ב-UTF-8, כך ש-CRLF של קובץ Windows מגיע כמו שהוא. תצוגת ההיסטוריה (/repo/api/file-at-commit) קוראת במסלול אחר, get_file_at_commit, ומקבלת את אותו טקסט לכל קובץ UTF-8 בלי BOM, חוץ משני מקרים ש-get_file_content מחזיר בהם טקסט: קובץ ש-_detect_binary_content מסווג כבינארי (בית NUL, או ריבוי תווי בקרה) חוזר שם בלי טקסט, וקובץ גדול מ-MAX_FILE_SIZE_FOR_DISPLAY נדחה שם ב-file_too_large. _try_decode_content שבמסלול ההוא מסיר BOM ומציג גם קובץ שאינו UTF-8, וקובץ כזה get_file_content לא מציג.

  • אין צנזור על התוכן. _run_git_command מעביר ב-_sanitize_output רק את ה-stderr של git ואת הפקודה שנכתבת ללוג, כי שם git מדפיס את ה-URL כשפקודת רשת נכשלת. ה-stdout הוא הנתונים עצמם, ושינוי שלו משבש את מה שמוצג. עד אוקטובר 2026 גם הוא עבר בניקוי, והקובץ הוצג משובש — ההסבר ברשומה של 11.10.2026 ב-What’s New.

  • מי רואה: אדמין בלבד. כל הנתיבים תחת /repo/ חסומים ב-_require_admin_for_repo_browser (before_request של ה-blueprint ב-webapp/routes/repo_browser.py), ו“ערוך / העתק“ ב-admin_required. במצב התחזות שניהם חסומים, כמו כל עמוד אדמין — חוץ מבקשה עם ?force_admin=1, מסלול המילוט שעוקף את חסימת ההתחזות בשניהם (is_impersonating_safe מחזיר עליו False, ו-admin_required מתיר אותו במפורש). is_admin נבדק לפניו, ולכן הוא לא פותח אותם למי שאינו אדמין.

  • אין חסימה לפי נתיב, בכוונה. .env או *.pem שנכנסו לריפו מוצגים לאדמין כמו כל קובץ אחר: זה הריפו שלו, והוא רואה אותו גם ב-GitHub. בכלי הריפו של ה-MCP יש חסימה כזו (מדיניות סינון סודות), כי שם התוכן עובר לסוכן AI.

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

ראו גם