בנו Python wheel מחוץ לרשת ופרסמו אותו בפנים

כבר יש לכם עבודת build שמייצרת wheel, ומאגר פרטי שאמור לקלוט אותו. הטעות היא לתת לעבודה שנייה לבנות מחדש מענף ולקרוא לתוצאה אותה מהדורה. העבירו את הקובץ שנבדק, תנו לו שם לפי התקציר, והשאירו את פרטי הגישה להעלאה בפנים. התיאור שלהלן עוקב אחרי חפץ אחד מריצת CI ציבורית לפרסם פנימי.

בנו במקום שבו הקוד כבר נמצא

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

python -m build --sdist --wheel --outdir dist
python -m twine check dist/*

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

תעדו מה הפיק אותם: שם החבילה והגרסה משמות הקבצים, גרסת הקוד, והרצת ה-workflow שיצרה אותם. מחרוזת גרסה לבדה אינה מזהה קובץ, מפני שאותה גרסה יכולה להיבנות פעמיים מ-commit שונים. כתבו את הגרסה לצד שמות הקבצים בתיאור החפץ, והתייחסו לתיעוד הזה כחלק מהמסירה.

העבירו בתים, לא הוראות לבנייה מחדש

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

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

sha256sum dist/*.whl dist/*.tar.gz
# keep the digests beside the run id in the artifact description

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

אמתו בפנים לפני ההעלאה

העבודה הפנימית מתחילה בבדיקה שהקובץ שהתקבל הוא הקובץ שאושר. השוו את התקצירים לתיעוד מעבודת ה-build, ולא לערך שחושב מחדש ממה שהגיע.

sha256sum -c digests.txt
python -m twine check dist/*

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

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

התמודדו עם תשובת הגרסה הכפולה

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

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

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

השאירו את פרטי הגישה להעלאה בצד אחד

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

הגבילו גם אילו workflows פנימיים רשאים להפעיל את הפרסם. טריגר ידני עם אישור נדרש הוא ברירת מחדל סבירה למהדורות; push לכל ענף אינו כזה.

המהדורה המוגמרת צריכה להשאיר שלושה דברים: קובצי ההפצה, התקצירים שלהם עם גרסת הקוד, ותיעוד מאגר שמראה את אותה גרסה.