ניהול אישורים של בקשות משיכה באמצעות CODEOWNERS

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

מבוא

התכונה Secure Source Manager‏ CODEOWNERS משתמשת בקבצים בבסיס קוד כדי להגדיר את המאשרים ברמת הקובץ. האפשרות הזו מאפשרת שליטה מדויקת יותר מאשר כללים אחרים של הסתעפות, כי אפשר להקצות בעלים ספציפיים לקבצים ספציפיים ולהגדיר קבוצות נפרדות של מאשרים.

התכונה CODEOWNERS מאפשרת לכם:

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

הפעלת בדיקה של בעלי קוד

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

מיקום וקדימות של קובץ CODEOWNERS

‫Secure Source Manager תומך בשתי אפשרויות להגדרת קובצי CODEOWNERS:

  1. קבצים מקוננים: CODEOWNERS קבצים בכל ספרייה חוץ מהספרייה .securesourcemanager. קובצי CODEOWNERS מקוננים משפיעים רק על הספרייה שלהם (כולל ספריות משנה), ונתיבי הקבצים בתוכם צריכים להיות מוגדרים ביחס לספרייה שבה נמצא קובץ CODEOWNERS. זו הגישה המומלצת לרוב תרחישי השימוש.

  2. קובץ ייעודי יחיד: אם אתם צריכים להבחין בין קובץ CODEOWNERS של Secure Source Manager לבין קבצים אחרים מסוג CODEOWNERS שמשמשים כלים אחרים (לדוגמה, .gitlab/CODEOWNERS), אתם יכולים להשתמש בקובץ יחיד שנמצא בנתיב .securesourcemanager/CODEOWNERS בתיקיית הבסיס של המאגר. אם הקובץ הזה קיים, Secure Source Manager מתעלם מכל שאר קובצי ה-CODEOWNERS באותו ענף, כולל קבצים מקוננים. הספרייה .securesourcemanager מזוהה רק בתיקיית הבסיס של המאגר.

אינטראקציה עם בקשות משיכה ואישורים

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

התחביר והמבנה של קובץ CODEOWNERS

קובץ CODEOWNERS מורכב מהערות, משורות כללים ומסמני קטעים. התגובות מתחילות ב-# והמערכת מתעלמת מהן.

פורמט של קו כלל

הפורמט הסטנדרטי של שורת כלל הוא:

[BRANCH_GLOB] PATH_GLOB [OWNERS...]

כאשר:

  • ‫BRANCH_GLOB: תבנית glob אופציונלית שמציינת לאילו ענפים הכלל חל. אם לא מציינים glob של ענף, הכלל חל על כל ענף שהקובץ CODEOWNERS נבדק בו (אם האפשרות CODEOWNERS מופעלת בכללי הענף). לדוגמה:

    • ‫main תואם רק לענף main.
    • ‫dev-* תואם לענפים שמתחילים ב-dev-.
    • ‫*-glob תואם לענפים שמסתיימים ב--glob.
    • ‫my-*-glob מתאים לענפים כמו my-feat-glob.

  • ‫PATH_GLOB: תבנית glob חובה שמציינת את נתיבי הקבצים שהכלל חל עליהם. התחביר של Secure Source Manager מבוסס על דפוסי gitignore.

    • אם תבנית לא מכילה /, או מכילה רק / כתו אחרון, זוהי תבנית glob שתואמת לכל ספרייה.
      • ‫*.js תואם לקובצי JavaScript בכל מקום.
      • ‫build/ תואם לספריות שנקראות build בכל מקום.
    • אם תבנית מכילה / בכל מקום אחר מלבד הסוף, המערכת מתייחסת אליה כנתיב יחסי למיקום של קובץ CODEOWNERS.
      • ‫docs/* מתאים לקבצים בתיקייה docs/ ביחס לקובץ CODEOWNERS.
      • ‫/*.js תואם לקובצי JavaScript באותה ספרייה כמו קובץ CODEOWNERS, אבל לא לקובצי JavaScript מוטמעים.
    • תבנית שמסתיימת ב-/ מתאימה רק לספריות ולתוכן שלהן באופן רקורסיבי. לדוגמה, build-*/ תואם לספריות כמו build-app/ ו-build-tool/ בכל מקום.
    • אם משתמשים ב-.securesourcemanager/CODEOWNERS, הנתיבים הם יחסיים לשורש המאגר.

  • ‫OWNERS: רשימה אופציונלית של כתובות אימייל של בעלים, מופרדות ברווחים. אם לא מציינים את הפרמטר הזה, הכלל הזה פועל כהחרגת נתיב.

בעלות ספציפית לענף

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

  • אם לא מציינים BRANCH_GLOB בתחילת הכלל, הכלל חל על כל הענפים.
  • המערכת מתעלמת מכל שורה עם תבנית glob של ענף שלא תואמת לענף הנוכחי.

יסודות התחביר

  • פירוש השדה: השדות מופרדים ברווחים.
    • שדות שמכילים @ מזוהים ככתובות אימייל של בעלים.
    • אם יש שדה אחד ללא @ לפני כתובות האימייל של הבעלים, הוא נחשב ל-PATH_GLOB. לדוגמה, ב-*.js user@example.com, ‏*.js הוא PATH_GLOB.
    • אם לפני כתובות האימייל של הבעלים יש שני שדות בלי @, השדה הראשון הוא BRANCH_GLOB והשני הוא PATH_GLOB. לדוגמה, ב-main *.js user@example.com, הערך של main הוא BRANCH_GLOB והערך של *.js הוא PATH_GLOB.
    • אותה לוגיקה חלה אם לא מציינים בעלים: שדה אחד הוא PATH_GLOB ושני שדות הם BRANCH_GLOB PATH_GLOB.
  • תחביר glob-style: ב-Secure Source Manager נעשה שימוש בתחביר glob-style רגיל (תחביר .gitignore-style) לביטויי נתיבים.
  • פרטים על תווים כלליים:
    • ‫** תואם לכל רצף של תווים, כולל /.
    • ‫* תואם לכל רצף של תווים, למעט /.
    • ‫? תואם לכל תו בודד, למעט /.
  • תלות באותיות רישיות: הקבצים CODEOWNERS תלויים באותיות רישיות.
  • זיהוי הבעלים: המערכת מזהה את הבעלים לפי כתובת האימייל. התו @ מבחין בין שדות של בעלים.
  • בכתובות האימייל של הבעלים, צריך להוסיף escape רק לתווים space ו-backslash.
  • תווים שמורים: המערכת שומרת את התווים הבאים. צריך להוסיף לוכסן הפוך (\) לפני התווים האלה בביטויי ענפים ונתיבים: [,‏ ],‏ ,‏ @,‏ *,‏ ?,‏ \,‏ {,‏ } ו-!.
  • אם ** משולב עם תווים אחרים, המערכת מתייחסת אליו כאל תו כללי רגיל. לדוגמה, /**/*.py תואם לכל קובץ Python בעומק כלשהו, /**.py נחשב ל-/*.py ותואם רק לקבצים בספריית הבסיס.

קטעים של כמה קבוצות אישור

שימוש ב[Section] שורות מקבץ כללים לאישורים נפרדים שנדרשים. האפשרות הזו שימושית כשרוצים לדרוש ביקורות מצוותים שונים, למשל צוות האבטחה או צוות בקרת האיכות.

  • הגדרת קטע: משתמשים בשורה בפורמט [Section Name] (אפשר להשתמש בכל שם בשפה טבעית).
  • מספר האישורים: אפשר להוסיף לסעיף סיומת אופציונלית [<approverCount>] כדי לציין מספר אישורים שונה מ-1. ספירה של 0 מציינת בעלים אופציונליים. לדוגמה, אפשר להשתמש בזה כדי להציג מומחים בקבצים מסוימים למטרות מידע, בלי לדרוש מהם לבדוק את הקבצים.
  • סיום קטע: קטע חל על כל הכללים שבאים אחריו עד שמתחיל הקטע הבא.
  • כללים שלא מחולקים לקטעים: המערכת מתייחסת לכללים שמופיעים לפני הגדרה של [Section] כקטע מאוחד אחד, שדורש אישור אחד כברירת מחדל.
  • איחוד: המערכת מתייחסת לקטעים עם אותו שם, ללא הבחנה בין אותיות רישיות לאותיות קטנות, גם אם הם נמצאים בכמה קבצי CODEOWNERS מקוננים, כאל קטע מאוחד יחיד, בהתאם לכללי העדיפות הרגילים.

החרגת נתיבים

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

התאמות לספריות פועלות רק אם הן מסתיימות ב-/ או אם הן לא מכילות תווים כלליים לחיפוש בחלק האחרון.

לדוגמה, *.py לא יתאים לספרייה מוסתרת .py/, אבל *.py/ כן.

יישוב סכסוכים ועדיפות

אם קיים קובץ .securesourcemanager/CODEOWNERS, המערכת תתעלם מכל שאר הקבצים CODEOWNERS. אם נתיב תואם לשתי שורות שונות באותו קטע, רק השורה האחרונה תחול. אם השורות נמצאות בקטעים שונים, שתיהן יחולו.

המערכת משתמשת בכלל עדיפות מבוסס-מיקום לקבצים מקוננים:

  • כללים בקובץ CODEOWNERS עם קינון עמוק יותר (מקומי יותר) מבטלים כללים תואמים בקובץ עם קינון רדוד יותר.
  • לקובץ CODEOWNERS בספריית הבסיס יש תמיד את העדיפות הכי נמוכה.

קובץ CODEOWNERS לדוגמה

קובץ CODEOWNERS לדוגמה, שמדגים את התחביר של CODEOWNERS:

# Un-sectioned rules; 1 approve required from any of owners of last matching line.
# Format: [BRANCH_GLOB] PATH_GLOB [OWNERS...]

# Make repo-admin the owner of all files of the current branch.
*   repo-admin@example.com      # No slash prefix; matches in sub-dirs too.
/**/* repo-admin@example.com      # Slash-prefix equivalent of prior line.

# Match all py files (including sub-dirs). Note repo-admin must be re-added.
*.py  repo-admin@example.com python-owner@example.com

# With repo-admin not included here, repo-admin no longer owns README.
/README.md readme-owner@example.com

/scratchpad.txt             # Can also override a path to have zero owners (path exclusion).

# Branch-specific syntax.
# Note that since un-sectioned rules are independent of sectioned rules,
# the above [Section] rules will still apply to this branch if they
# aren't modified to add e.g. `main ` as a prefix.
dev-* *             # Remove all owners reqs on dev branches.
dev-* /experimental/ exp-owner@example.com   # dev-specific owners.

# Make repo admin own all CODEOWNERS files, regardless of any prior rules.
CODEOWNERS repo-admin@example.com

# Section; 1 approval required *in addition* to owners outside this section.
[Security Team]
/secure-directory/ security-expert@example.com security-reviewer@example.com
/**/*secure\ me* security-expert@example.com security-reviewer@example.com

# Section w/ req approval count of 2 instead of 1.
[Doc Team][2]
/docs doc-expert@example.com doc-reviewer@example.com
*.md doc-expert@example.com doc-reviewer@example.com

תאימות למערכות אחרות לניהול קוד מקור

‫Secure Source Manager מספק תחביר מוכר ונייד עם מערכות אחרות לניהול קוד מקור. התחביר של Secure Source Manager CODEOWNERS תואם לתחביר של GitHub CODEOWNERS, ותואם באופן חלקי לתחביר של GitLab CODEOWNERS, כולל ספירות אישורים חלקיות כמו [Section Name][2].

ההטמעה של Secure Source Manager של CODEOWNERS לא תומכת בתחביר של GitLab‏ !path לשלילת נתיב. מידע על החרגת נתיבים ב-Secure Source Manager זמין במאמר החרגת נתיבים. בנוסף, Secure Source Manager לא תומך בבעלים שמוגדרים כברירת מחדל בכותרות של קטעים – לדוגמה, [Section Name] @owner1 @owner2.

אימות וטיפול בשגיאות

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

אכיפה

אמצעי הגנה לפני שליחה אוכף את בדיקת שגיאות התחביר בכל ענף שבו מפעילים את כלל הענף של בעלי הקוד. כך לא תבצעו בטעות צ'ק-אין לקבצים פגומים.CODEOWNERS

טיפול בשגיאות תחביר

בדיקות לפני שליחה פועלות רק בענפים שבהם האפשרות Require Code Owner Review on Pull Requests (נדרשת בדיקה של בעלי הקוד בבקשות משיכה) מופעלת. אם קובץ CODEOWNERS לא תקין מבחינת התחביר שלו מועבר לענף, ובדיקת בעלי קוד מופעלת מאוחר יותר בענף הזה, המערכת מטפלת בשגיאות בצורה חלקה:

  • המערכת מתעלמת משורות שלא ניתן לנתח אותן להגדרת קטע, לשורת כלל או לפורמט של הערה.
  • אם מספר האישורים הוא שלילי, המערכת מתייחסת אליו כאל 0.
  • המערכת ממשיכה לנתח ולהחיל את כל השורות התקינות כרגיל.

המאמרים הבאים