קובץ הנעילה של GitHub Actions מקבע את קוד הפעולות, אך לא את כל ה-CI

האם אפשר לסמוך על GitHub Actions כאשר workflow מפנה ל-action באמצעות תג כמו @v3? קובץ הנעילה מבהיר איזה commit של ה-action יופעל, גם אם התג יועבר בהמשך. הצוות יכול לעיין בעדכוני התלויות בהפרש השינויים ולנהל רשימה שניתנת לבדיקה של ה-actions שבהם משתמש CI. הגבול המעשי: קובץ הנעילה מכסה actions שנקראים בשלבים, ואילו reusable workflow שנקרא ברמת ה-job צריך לקבע בנפרד. המנגנון המתואר זמין ב-GitHub Enterprise Cloud.

מה בדיוק מקבע קובץ הנעילה?

הפניות לענפים ולתגים נוחות, אבל הגרסה שאליה הן מצביעות עשויה להשתנות. רשומה כמו uses: octo-org/deploy-action@v3 מצביעה על שם תג; GitHub פותר את ההפניה ל-commit בזמן ההרצה. אם בעלי הפרויקט יעבירו את התג, הרצה הבאה ללא תלות מקובעת עלולה לקבל קוד אחר.

לפי התיעוד של GitHub על קובצי נעילה, הקובץ .github/workflows/actions.lock מאחסן הפניות לתלויות ואת ה-commit SHA המתאים, כולל תלויות טרנזיטיביות — actions שבהן משתמשים actions אחרים. הקובץ נוצר באמצעות תוסף GitHub CLI בשם gh actions-lock; לא עורכים אותו ידנית.

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

לאחר מכן, עדכון תלות הופך לשינוי גלוי במאגר: הצוות יכול לבדוק את שינוי ה-commit, לדון בו ולאשר אותו בתהליך סקירה רגיל. קובץ הנעילה מסייע לבקר את קוד ה-actions ולשמור על עקביות התלויות; כשלעצמו, הוא אינו מאשר שהקוד שנבחר בטוח.

היכן מסתיים היקף הקיבוע?

קריאה ל-reusable workflow בתוך jobs.<job_id>.uses אינה מקובעת בקובץ הנעילה של המאגר שקורא לו. התלויות של reusable workflow שייכות למאגר שבו ה-workflow מוגדר. כדי לקבע את הקריאה עצמה, יש לציין commit SHA מלא; כדי לקבע את ה-actions שלו במאגר המקור, דרוש קובץ נעילה משלו.

קובץ הנעילה מבקר את קוד ה-actions, אך לא קלטים אחרים של תהליך הבנייה, כגון פרמטרים שהועברו ל-action, סודות או תמונת ה-runner. הוא עונה על שאלה מסוימת: איזה commit של קוד ה-action יופעל? לרכיבים האחרים האלה נדרשים כללי ניהול משלהם.

יש גם מקרה מיוחד — action מקומי שנקרא באמצעות נתיב כמו uses: ./. לפי הוראות GitHub, התוסף gh actions-lock אינו מקבע או מנתח נתיב מקומי של action. אם action כזה משתמש ב-actions אחרים, יש לנהל את התלויות בנפרד; בתיעוד מתוארת אפשרות להעביר הפניות ל-actions מקומיים לפורמט $/.

לכן, רשומה אחת בקובץ הנעילה עשויה להיות חלק משרשרת, אך אינה מחליפה בקרה על כל החוליות בה. עבור reusable workflow חיצוני, בדקו שהקריאה מקובעת ומה מצב מאגר המקור; עבור actions מקומיים, בדקו כיצד התלויות שלהם מובאות בחשבון.

איך להטמיע בקרה בלי לעצור את CI במפתיע?

GitHub ממליצה תחילה לבצע פיילוט במאגרים וב-workflows שנבחרו. המדיניות Require lockfile חוסמת הרצה של workflows הכלולים בה ללא קובץ נעילה תקין, לרבות workflows ללא תלויות uses:. מצב Evaluate של המדיניות זמין רק ב-GitHub Enterprise Cloud. לכן, הכינו תחילה את היקף ההחלה ואת מנגנון העדכון האוטומטי, ורק לאחר מכן הפעילו את הכלל המחייב.

1. בדקו את ההפניות המקוריות. לפני יצירת קובץ הנעילה, ודאו שה-actions מצביעים לגרסאות שהצוות אכן רוצה לקבע. המחולל מקבע את ה-commit שנפתר מההפניה הנוכחית.
2. צרו את קובץ הנעילה ועברו עליו. התקינו את התוסף gh-actions-lock, הריצו gh actions-lock משורש המאגר ועברו על כל הפרש השינויים, לרבות הפניות uses שעודכנו.
3. הגדירו עדכון ובדיקה שוטפים. Dependabot יכול לעדכן את הרשומות המתאימות עבור workflows שכבר חוברו. ב-CI אפשר להגדיר משימת בדיקה ל-pull request באמצעות gh actions-lock --verify, כדי לזהות קובץ נעילה מיושן לפני הבנייה הראשית.
4. הקצו סוקרים. הוסיפו את .github/workflows/actions.lock ל-CODEOWNERS ודרשו מאחראי אבטחת הבנייה לבדוק שינויים.
5. בצעו פיילוט למדיניות. התחילו במאגרים וב-workflows שחוברו. במצב Evaluate נתחו את התוצאות; לפני מעבר למצב Active, ודאו שכל ה-workflows שבתחום המדיניות הוכנו ושקובצי הנעילה נשארים עדכניים.

Require lockfile והמדיניות הנפרדת Require actions to be pinned to a full-length commit SHA הן כללים שונים; GitHub מציינת שאפשר להשאיר את שניהם פעילים. גם לבדיקה ב-CI ולמדיניות מחייבת יש תפקידים שונים: הראשונה מזהה קובץ מיושן במהלך העבודה על pull request, והשנייה חוסמת הרצה של workflow שאינו עומד בדרישה.

דוגמה: עדכון action לפריסה

נניח ש-workflow מפרסם יישום באמצעות octo-org/deploy-action@v3. תחילה הצוות בודק לאיזו גרסה ההפניה נפתרת, לאחר מכן מריץ gh actions-lock ובוחן את הפרש השינויים ב-workflow יחד עם רשומת ה-commit בקובץ הנעילה. בעת עדכון ה-action, הסוקר רואה את השינויים בהפניות וב-commit המקובע; כך אפשר להעריך עדכון מסוים, במקום להניח שתג שניתן להזיז תמיד יצביע על אותו קוד.

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

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