CI/CD Guide

חוקים קשיחים

  • אין git clean/reset ב‑CI

  • אין sudo

  • טסטים ירוצו בסביבות מבודדות; IO רק תחת /tmp

  • התיעוד נכשל על אזהרות (fail_on_warning: true)

  • runs-on הוא תווית אובונטו שנוקבת בגרסה, ולא תווית שזזה לבד — ראו תווית ה-runner

סטטוסים נדרשים

  • 🔍 Code Quality & Security

  • Unit Tests (3.11)

  • Unit Tests (3.12)

  • Unit Tests md-heavy (3.11)

  • Unit Tests md-heavy (3.12)

שמות הסטטוסים של Unit Tests נבנים מהמטריצה של הג’וב unit-tests ב-.github/workflows/ci.yml (label ו-python-version). אותם שמות כתובים ביד גם בקבצים אחרים בריפו, ו-tests/test_required_checks_are_listed.py משווה למטריצה כל קובץ כזה שרשום בו (LISTS), כולל העמוד הזה. הוא נכשל גם כשעותק מופיע בקובץ שאינו רשום בו, אלא אם הקובץ מסומן שם כתמונת מצב ולא כרשימה שפועלים לפיה (SNAPSHOTS). עמוד שרק צריך להזכיר את הרשימה מפנה לכאן במקום להעתיק אותה.

סטטוס חדש אינו חוסם מיזוג עד שמסמנים אותו כבדיקת חובה בכלל שמגן על main בהגדרות של GitHub (Require status checks to pass before merging). GitHub מציע לבחירה רק בדיקה שעברה בהצלחה בריפו בשבעת הימים האחרונים (GitHub Docs, ”Troubleshooting required status checks“), ולכן מסמנים אותה אחרי שה-CI של ה-PR שהוסיף אותה עבר.

ריכוז CI (Overview)

  • Code Quality & Security – בדיקות סטטיות ואבטחה

  • Unit Tests (3.11/3.12) ו-Unit Tests md-heavy (3.11/3.12) – טסטי היחידה, בשני מסלולים לכל גרסת פייתון שרצים במקביל. Unit Tests מריץ את כל הטסטים חוץ מאלה שמסומנים md_heavy, ו-Unit Tests md-heavy מריץ רק אותם: טסטי פרסר ה-Markdown הכבדים (ראו Testing Guide). כל מסלול מדווח סטטוס חובה משלו, והמסלול md-heavy אינו מרים את MongoDB ואת Redis (services של unit-tests). coverage נמדד ונשלח ל-Codecov רק במסלולים שהמטריצה מסמנת ב-coverage (רשומת include לפי גרסת פייתון), כדי לא לשלם פעמיים על ההאטה שהוא מוסיף לטסטים, וההעלאות של אותו קומיט מתמזגות ב-Codecov לדוח אחד.

  • JS Tests (node) – טסטי הצד-לקוח שב-tests/*.test.js. כל קובץ הוא סקריפט עצמאי שמריץ את עצמו ויוצא עם קוד שגיאה בכשל, בלי רץ טסטים חיצוני. repo-history.test.js מדולג במפורש: הוא כתוב בסגנון describe/it ואין בפרויקט רץ שמספק אותם. אינו סטטוס נדרש – הכשל מופיע ב-PR אך אינו חוסם מיזוג.

  • Performance Tests – טסטי ביצועים (ברירת מחדל: הכל; Draft + perf-light: רק קלים). דוחות זמני ריצה נשמרים כארטיפקטים.

קישורים מהירים:

  • Actions (Performance): https://github.com/<OWNER>/<REPO>/actions/workflows/performance-tests.yml

  • ריצת ה‑PR: בתגובות ה‑PR מתווסף קישור אוטומטי ל‑Run ול‑Artifact.

תווית ה-runner

כל runs-on תחת .github/workflows הוא תווית אובונטו שנוקבת בגרסה, וכל הג’ובים רצים על אותה תווית. tests/test_workflow_runner_labels.py אוכף את שני הכללים, ולכן התווית עצמה כתובה רק ב-workflows ולא כאן. הצורה המותרת מוגדרת ב-PINNED_LABEL שבטסט, כצורה שחייבת להתקיים ולא כרשימה של תוויות אסורות — למה, ב-docstring של הטסט.

למה לא ``ubuntu-latest``. זו לא גרסה אלא מצביע ש-GitHub מעבירים לגרסה חדשה מתי שהם מחליטים, והמעבר הדרגתי: את המעבר ל-Ubuntu 26.04 הם הכריזו כתהליך של כמה שבועות שמתחיל ב-19 באוקטובר 2026 (actions/runner-images#14748). בזמן הזה חלק מהג’ובים רצים על הגרסה הישנה וחלק על החדשה, ומה שנשבר נראה כמו כישלון אקראי שעובר בהרצה חוזרת. כשהתווית נעוצה, המעבר קורה רק כשמחליטים עליו.

התווית נועצת את גרסת אובונטו, לא את התמונה. GitHub מעדכנים את התמונה שמאחורי אותה תווית — התוכנה המותקנת ואפילו הקרנל — והעדכון מגיע ל-runners בהדרגה, כך שאותו כישלון אקראי יכול לקרות גם בתווית נעוצה. באוקטובר 2026 עדכון כזה העביר את ubuntu-24.04 מקרנל 6.17 לקרנל 7.0, ו-mongod של 8.0 הפסיקה לעלות על חלק מה-runners: GLIBC_TUNABLES בשירותי המונגו. כדי לדעת על איזו תמונה ג’וב רץ, קוראים את שורת Version: בקבוצה Runner Image של הצעד Set up job.

שדרוג לגרסה חדשה הוא PR אחד שמחליף את התווית בכל הקבצים. לפני שממזגים בודקים בריצות של הענף של ה-PR אילו ג’ובים רצו על התווית החדשה — בצעד Set up job של כל ג’וב, הקבוצה Runner Image כותבת את התמונה בשורת Image:. ג’וב שלא רץ עליה לפני המיזוג יפגוש אותה לראשונה אחריו. את זה לא מסיקים מה-``on:`` של הקובץ, כי הוא מטעה לשני הכיוונים. push רץ מקובץ ה-workflow שבענף שנדחף, גם כשהקובץ עוד לא מוזג, ולכן push שמסונן רק ב-paths (בלי branches) רץ על הענף של ה-PR כשהוא נוגע בנתיבים האלה, ו-push שמוגבל ל-main לא. ומנגד, schedule, workflow_run, issue_comment ו-pull_request_target רצים בהקשר של ענף ברירת המחדל — ה-GITHUB_SHA שלהם הוא הקומיט האחרון שם (תיעוד GitHub, ”Events that trigger workflows“) — ולכן גם כשהם רצים בזמן שה-PR פתוח, הם עדיין על התווית הישנה. לפני הרצה ידנית של workflow מהענף בודקים מה ה-workflow_dispatch שלו מפעיל: ב-deploy.yml הוא פורס (ראו את ה-if: של deploy-staging).

עד מתי תווית ישנה זמינה: לפי ה-README של actions/runner-images (נבדק ב-2026-10-05), GitHub מחזיקים לכל היותר שתי גרסאות GA במקביל, ומתחילים להוציא את הישנה משימוש כשגרסה חדשה עוברת ל-GA.

פואמה על PR

.github/workflows/pr-poem.yml כותב פואמה קצרה בעברית על כל PR חדש, ומפרסם אותה כתגובה אחת על ה-PR. אין בה ביקורת קוד. הפואמה נשענת על הכותרת, על התיאור ועל שמות הקבצים שהשתנו, ולא על ה-diff. זה אינו סטטוס נדרש: הרצה שנכשלה מופיעה ב-PR ואינה חוסמת מיזוג.

  • מתי רץ: כשנפתח PR (opened), וכשטיוטה מסומנת כמוכנה לסקירה (ready_for_review). טיוטה מקבלת את הפואמה רק כשהיא מוכנה. PR מ-fork מדולג תמיד, כי ל-fork אין גישה ל-secrets.

  • פעם אחת לכל PR. התגובה נושאת את MARKER, הערת HTML שלא מוצגת. כל הרצה בודקת קודם אם כבר יש על ה-PR תגובה עם הסימון, ואם יש — יוצאת בלי לעשות כלום. הפואמה של CodeRabbit לא נחשבת, ושתיהן יכולות להופיע על אותו PR. ה-concurrency של הג’וב, לפי מספר ה-PR, מוודא ששתי הרצות על אותו PR לא בודקות במקביל. כדי לקבל פואמה חדשה מוחקים את התגובה ומריצים ידנית.

  • מה צריך להגדיר: ה-secret ANTHROPIC_API_KEY, ב-Settings ← Secrets and variables ← Actions ← Secrets. בלעדיו ההרצה מסתיימת בהצלחה עם אזהרה, ובלי פואמה. כדי שהתגובה תתפרסם בשם GitHub App ולא בשם github-actions, מגדירים באותו מסך גם את POEM_APP_ID ואת POEM_APP_PRIVATE_KEY — כל התוכן של קובץ ה-.pem של ה-App. ל-App צריך הרשאת Pull requests: Read and write, והוא צריך להיות מותקן על הריפו. הג’וב מנפיק ממנו טוקן התקנה דרך actions/create-github-app-token. כשאחד משני ה-secrets חסר, הפואמה מתפרסמת בשם github-actions עם אזהרה. כשהם מוגדרים אבל הנפקת הטוקן נכשלת, למשל בגלל מפתח שגוי, ההרצה נכשלת ולא נופלת לטוקן הרגיל. כך זה גם ב-PR של Dependabot, כי GitHub מתייחסים ל-workflow ש-Dependabot הפעיל כמו לזה של fork, ולא מעבירים לו secrets (תיעוד GitHub, ”Events that trigger workflows“).

  • המודל הוא DEFAULT_MODEL ב-.github/pr-poem/pr_poem.py. כדי להחליף אותו בלי לשנות קוד, מגדירים repository variable בשם POEM_MODEL, באותו מסך בלשונית Variables.

  • הרצה ידנית על PR קיים: Actions ← PR Poem ← Run workflow, עם מספר ה-PR. הכפתור זמין רק כשה-workflow נמצא בענף ברירת המחדל (תיעוד GitHub, ”Manually running a workflow“), כלומר אחרי המיזוג.

  • ההנחיה והדוגמאות הן .github/pr-poem/prompt.md ו-.github/pr-poem/examples.md, ושתיהן נשלחות למודל כמו שהן, כ-system. הן והסקריפט נלקחים תמיד מענף ברירת המחדל, ולא מה-PR (ה-ref של ה-checkout ב-pr-poem.yml), כי הקוד שרץ שם מקבל את המפתח, ואת הקבצים האלה אפשר לשנות בכל PR — גם בלי ההרשאה ש-GitHub דורשים לשינוי של workflow. לכן PR שמשנה אותם מקבל פואמה לפי הגרסה שבענף ברירת המחדל, והשינוי חל רק אחרי המיזוג. כדי לראות את הבקשה שתישלח, בלי המפתח, בלי לקרוא ל-Anthropic ובלי לפרסם:

    python .github/pr-poem/pr_poem.py --pr 3583 --repo amirbiron/CodeBot --dry-run
    
  • הטסטים: tests/test_pr_poem.py, בלי רשת. ההרצה המלאה שם עוברת דרך דמה של http_json, שנכשלת על כל קריאה שהטסט לא ציפה לה. כיוון השורות בתגובה נמדד בכרומיום ב-tests/test_pr_poem_rtl_browser.py, שמדולג כשאין Chromium, ולכן גם ב-CI.

אישו על כשל אחרי מיזוג

.github/workflows/notify-post-merge-issue.yml פותח אישו כשריצה על main אחרי push נכשלת, ומשייך אותו לבעל הריפו. כשריצה מאוחרת יותר של אותו workflow עוברת, הוא סוגר אותו.

  • אילו ריצות הוא בודק. את ה-workflows שברשימה workflows של הטריגר workflow_run, לפי השדה name: שלהם. היום אלה ci.yml (CI/CD Pipeline) ו-deploy.yml (🚀 Code Keeper Bot CI/CD). שניהם מריצים את אותם טסטים, אבל לא באותה צורה: ci.yml מחלק אותם בין כמה תהליכים (-n auto), ו-deploy.yml מריץ את כולם ברצף בתהליך אחד. טסט שמשאיר מצב שמפיל טסט אחר נכשל רק כששניהם רצים באותו תהליך, ולכן לפעמים רק ב-deploy.yml (דוגמאות ב-Testing Guide). workflow חדש שמריץ טסטים על main צריך להיכנס לרשימה, אחרת כשל בו לא יפתח אישו.

  • מה נחשב כשל. ג’וב שה-conclusion שלו אינו success ואינו skipped (FAILED_JOBS_JQ בראש הקובץ), או unit-durations.json מארטיפקט unit-durations-* שמדווח על טסטים שנכשלו. skipped אינו כשל: ג’וב שדולג לא רץ, ו-deploy.yml מדלג על חלק מהג’ובים שלו בכל ריצה על main.

  • אישו לכל workflow. שם ה-workflow נכנס לכותרת (Post-merge failure: <שם> on main @ <sha>), וריצה מוצלחת סוגרת רק את האישו הפתוח האחרון של אותו workflow. כשאותו טסט נכשל בשני ה-workflows, נפתחים שני אישוז.

  • סגירה רק על קומיט שמכיל את הכשל. ריצה מוצלחת סוגרת את האישו רק כשהקומיט שלה מכיל את הקומיט שנכשל, כלומר כשזה אותו קומיט או צאצא שלו בהיסטוריה של git. ההחלטה לא נשענת על הסדר שבו הריצות מסתיימות: ל-deploy.yml אין concurrency, ולכן ריצות של קומיטים סמוכים רצות במקביל, וריצה שנכשלת מסתיימת לפני ריצה מוצלחת, כי היא עוצרת בכשל הראשון. בלי הבדיקה, הצלחה של קומיט ישן שמגיעה אחרי הכשל הייתה סוגרת את האישו של קומיט חדש יותר שעדיין שבור. את ה-SHA המלא של הקומיט שנכשל האישו נושא בסימון נסתר בגוף שלו (POST_MERGE_SHA_MARKER בראש הקובץ), והסגירה משווה אותו לקומיט שהצליח דרך ה-API של GitHub להשוואת קומיטים. הסגירה קוראת את הסימון רק מהגוף, ולכן גם כשכשל חוזר מוסיף תגובה לאישו קיים עם אותה כותרת, הסימון נכנס לגוף אם הוא חסר שם, למשל באישו שנפתח לפני שהסימון נוסף. אישו שעדיין אין בו סימון נשאר פתוח. ההחלטות האלה נבדקות ב-tests/test_notify_post_merge_issue.py, שמריץ ב-node את הסקריפטים עצמם מתוך ה-YAML.

בדיקות מומלצות

pytest
pytest --cov=. --cov-report=html

בנייה של התיעוד

cd docs
sphinx-build -b html . _build/html -W --keep-going

קישורים