חיבור ל-Cloud Build

בדף הזה מוסבר איך להפעיל build באופן אוטומטי מ-Secure Source Manager באמצעות קובצי הגדרות של Cloud Build וקובץ YAML של טריגרים במאגר Secure Source Manager.

כברירת מחדל, Secure Source Manager משתמש בסוכן שירות שמנוהל על ידי Google כדי ליצור אינטראקציה עם Cloud Build ועם משאבים אחרים. כדי לבודד את ההרשאות של הצוות, מומלץ להגדיר זהות לכל מאגר על ידי שיוך חשבון שירות בניהול המשתמש למאגר. ‫Secure Source Manager משתמש בחשבון השירות שמנוהל על ידי המשתמש שמשויך למאגר כדי להפעיל בנייה.

בניגוד לסוכן השירות שמוגדר כברירת מחדל, אתם יכולים להגדיר חשבון שירות בניהול המשתמש עם ההרשאה iam.serviceAccounts.actAs בחשבונות שירות מותאמים אישית של Cloud Build. כך אפשר להריץ build באמצעות חשבונות שירות בהתאמה אישית, תוך הגבלת הרשאות ה-build למאגר הזה.

לפני שמתחילים

1. יצירת מופע של Secure Source Manager
2. יצירת מאגר Secure Source Manager

3. הגדרת חשבון שירות שצוין על ידי המשתמש ב-Cloud Build. כדי לאפשר ל-Cloud Build לקרוא ממאגר Secure Source Manager, צריך להעניק לחשבון השירות של Cloud Build (חשבון השירות שמוגדר כברירת מחדל או חשבון שירות בניהול המשתמשים) את התפקידים הבאים:

   • ‫Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) במופע של Secure Source Manager.
   • Secure Source Manager Repository Reader במאגר.

   בהתאם לתרחיש לדוגמה, יכול להיות שחשבון השירות ב-Cloud Build יזדקק לתפקידים נוספים, למשל:

   • כדי לאחסן יומני build ב-Cloud Logging, צריך להעניק לחשבון השירות של Cloud Build את התפקיד Logs Writer‏ (roles/logging.logWriter).
   • כדי לגשת לסודות ב-Secret Manager, צריך להקצות לחשבון השירות של Cloud Build את התפקיד Secret Manager Secret Accessor (roles/secretmanager.secretAccessor).

   מידע על יומני build זמין במאמר הגדרת יומני build.

4. אם הבנייה שלכם מורצת במאגרי עובדים, צריך להעניק לחשבון השירות שמנוהל על ידי המשתמש במאגר התפקיד Cloud Build WorkerPool User ‏ (roles/cloudbuild.workerPoolUser) בפרויקט שבו מורצת הבנייה.

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לחיבור מאגר Secure Source Manager ל-Cloud Build, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

• Secure Source Manager Repository Writer (roles/securesourcemanager.repoWriter) במאגר
• ‫Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) במופע Secure Source Manager

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

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

במאמרים בקרת גישה באמצעות IAM והענקת גישה של משתמשים למופע מוסבר איך נותנים תפקידים ב-Secure Source Manager.

תפקידים נדרשים של חשבון שירות

כדי לקשר את Secure Source Manager ל-Cloud Build, צריך להגדיר הרשאות IAM לזהות לכל מאגר.

הגדרת זהות לכל מאגר

כדי להשתמש בזהות לכל מאגר, צריך להגדיר הרשאות.

הערה: כברירת מחדל, אפשר להשתמש רק בחשבון שירות בניהול המשתמשים שנמצא באותו Google Cloud פרויקט כמו המאגר והגרסאות. אם חשבון השירות בניהול המשתמשים נמצא בפרויקט אחר (הגדרה בין פרויקטים), צריך להשבית את אילוץ מדיניות הארגון iam.disableCrossProjectServiceAccountUsage בפרויקט שבו נמצא חשבון השירות בניהול המשתמשים. מידע נוסף זמין במאמר בנושא הגדרה של חשבון שירות בכמה פרויקטים.

1. משתמש: המשתמש שמגדיר את חשבון השירות של המאגר צריך את התפקיד משתמש בחשבון שירות (roles/iam.serviceAccountUser) בחשבון השירות בניהול המשתמש. ההרשאה הזו נבדקת במהלך יצירה או עדכון של מאגר.

2. סוכן השירות של Secure Source Manager: מקצים לסוכן השירות של Secure Source Manager בפרויקט המאגר את התפקיד יצירת אסימונים בחשבון שירות (roles/iam.serviceAccountTokenCreator) בחשבון השירות בניהול המשתמש.

   כתובת האימייל של סוכן השירות של Secure Source Manager היא בפורמט [e-mail], כאשר REPOSITORY_PROJECT_NUMBER הוא מספר הפרויקט שמארח את המאגר.

3. חשבון שירות בניהול המשתמש:

   • נותנים לחשבון השירות בניהול המשתמש את התפקיד משתמש בחשבון שירות (roles/iam.serviceAccountUser) בחשבון השירות המותאם אישית של Cloud Build (בפרויקט המאגר).
   • נותנים לחשבון השירות בניהול המשתמש את התפקיד עריכה ב-Cloud Build (roles/cloudbuild.builds.editor) ואת התפקיד צרכן של שימוש בשירות (roles/serviceusage.serviceUsageConsumer) בפרויקט שבו מופעלות הבנייות.

במאמר איך נותנים או מבטלים תפקידים בודדים מוסבר איך מקצים תפקידים ב-IAM.

יצירת קובץ תצורת build

קובץ תצורת build מגדיר את השדות שנדרשים ל-Cloud Build כדי לבצע את משימות ה-build. אפשר לכתוב את קובץ הגדרות ה-build באמצעות תחביר YAML.

אתם יכולים ליצור קובצי תצורת build בענף או בענפים שמהם אתם רוצים לבצע build.

כדי ליצור קובץ תצורת build:

1. בממשק האינטרנט של Secure Source Manager, בוחרים את מאגר הקוד שרוצים לקשר ל-Cloud Build.
2. בוחרים את הענף שממנו רוצים לבצע את הבנייה באמצעות Cloud Build.

3. יוצרים קובץ תצורת build. כדי ליצור קובצי תצורת build, פועלים לפי ההוראות במאמר בנושא יצירת קובץ תצורת build.

4. שומרים את השינויים בהסתעפות.

יצירת קובץ טריגרים

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

כדי ליצור קובץ תצורה של טריגרים:

1. במאגר המקומי או בממשק האינטרנט של Secure Source Manager, עוברים אל ענף ברירת המחדל.

2. יוצרים קובץ בשם .cloudbuild/triggers.yaml.

3. מגדירים את הטריגר בקובץ .cloudbuild/triggers.yaml:

   triggers:
   - name: TRIGGER_NAME
     project: PROJECT_ID
     configFilePath: CLOUD_BUILD_CONFIG_PATH
     eventType: EVENT_TYPE
     ignoredGitRefs: IGNORED_GIT_REFS
     includedGitRefs: INCLUDED_GIT_REFS
     serviceAccount: SERVICE_ACCOUNT
     includedFiles: INCLUDED_FILES
     ignoredFiles: IGNORED_FILES
     disabled: DISABLED_BOOL
     substitutions:
       _VARIABLE_NAME: VARIABLE_VALUE
       OVERRIDE_VARIABLE_NAME: OVERRIDE_VARIABLE_VALUE
   

   מחליפים את מה שכתוב בשדות הבאים:

   • TRIGGER_NAME בשם של הטריגר. שמות של טריגרים יכולים להכיל רק תווים אלפאנומריים ומקפים, והם לא יכולים להתחיל או להסתיים במקף. אורך השם של הטריגר מוגבל ל-64 תווים.
   • ‫PROJECT_ID במזהה הפרויקט ב- Google Cloud שבו הפעלתם את Cloud Build. השדה הזה הוא אופציונלי. ברירת המחדל היא פרויקט Secure Source Manager.
   • ‫CLOUD_BUILD_CONFIG_PATH עם הנתיב לקובץ ההגדרות של Cloud Build שרוצים להשתמש בו בשביל הטריגר הזה. השדה הזה הוא אופציונלי. ערך ברירת המחדל הוא .cloudbuild/cloudbuild.yaml.

   • ‫EVENT_TYPE עם סוג האירוע שרוצים להפעיל את הבנייה. האפשרויות הן:

     • ‫push כדי להפעיל את הטריגר כשמתבצעת דחיפה לענפים שצוינו
     • ‫pull_request כדי להפעיל pull request בענפים שצוינו

     השדה הזה הוא אופציונלי. ערך ברירת המחדל הוא push.

   • ‫INCLUDED_GIT_REFS עם פורמט אופציונלי של ביטוי רגולרי RE2 שמתאים להפניות של Git שרוצים להפעיל בשבילן בנייה. ערך ברירת המחדל הוא ריק. ערך ריק מציין שאין הגבלות.

   • ‫IGNORED_GIT_REFS עם ביטוי רגולרי אופציונלי בפורמט של ביטוי רגולרי RE2, שמתאים להפניות Git שלא רוצים להפעיל בשבילן בנייה. ערך ברירת המחדל הוא ריק. ערך ריק מציין שאין הגבלות. השדה ignoredGitRefs נבדק לפני השדה includedGitRefs. מידע נוסף על השדות האלה זמין במאמר בנושא סכימת קובץ הטריגרים.

   • ‫SERVICE_ACCOUNT מחליפים בחשבון השירות ב-Cloud Build שבו רוצים להשתמש בשביל הבנייה, בפורמט projects/PROJECT_ID/serviceAccounts/ACCOUNT. מחליפים את ACCOUNT בכתובת האימייל או במזהה הייחודי של חשבון השירות. אפשר להשתמש בחשבון השירות שמוגדר כברירת מחדל ב-Cloud Build או בחשבון שירות בניהול המשתמש. אי אפשר להשתמש בחשבון השירות מדור קודם של Cloud Build בגלל המגבלות שלו.

   • ‫INCLUDED_FILES עם ביטוי רגולרי אופציונלי בפורמט RE2 שתואם לקבצים שרוצים להפעיל בשבילם build.

     אם חלק מהקבצים ששונו לא תואמים לשדה המסנן ignoredFiles, והקבצים ששונו תואמים לשדה המסנן includedFiles, יופעל build. ערך ברירת המחדל הוא ריק. ערך ריק מציין שאין הגבלות.

   • IGNORED_FILES עם ביטוי רגולרי אופציונלי בפורמט RE2 שתואם לקבצים שלא רוצים להפעיל בשבילם build.

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

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

   • VARIABLE_NAME בשם של משתנה שרוצים להוסיף לקובץ של הטריגרים.

   • VARIABLE_VALUE בערך של המשתנה.

   • ‫OVERRIDE_VARIABLE_NAME בשם ברירת המחדל של משתנה ההחלפה ב-Secure Source Manager. מידע על משתני ברירת המחדל הזמינים להחלפה מופיע בקטע 'החלפות' במאמר סכימת קובץ הטריגרים.

   • OVERRIDE_VARIABLE_VALUE בערך שרוצים להשתמש בו במקום ערך ברירת המחדל של משתנה ההחלפה שמוגדר כברירת מחדל.

4. מבצעים Commit של קובץ ההגדרות של הטריגר לסניף ברירת המחדל.

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

   ‫Secure Source Manager קורא את קובצי ההגדרות ואת ה-SHA של הקומיט או את הפניה ל-Git שמשויכים לסוגי האירועים הבאים:

   • עבור אירועים מסוג push, ‏ Secure Source Manager יקרא את ה-SHA של הקומיט או את Git ref כשהפעולה push תושלם.
   • עבור אירועים מסוג pull_request, המערכת של Secure Source Manager קוראת את ה-SHA של הקומיט או את הפניה ב-Git כשמושכים את השינויים מבקשת משיכת השינויים.

צפייה בסטטוס של ה-build

כשגרסת build מופעלת על ידי אירוע של בקשת push או pull, הסטטוס של הקומיט ושל גרסת ה-build מוצג בממשק האינטרנט של Secure Source Manager.

הערכים האפשריים של סטטוס הבנייה הם:

• ‫SUCCESS: הבנייה הושלמה בהצלחה.
• אזהרה: הייתה בעיה בניסיון לבצע build.
• FAILURE: ה-build נכשל במהלך הביצוע.

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

כדי לראות את סטטוס הבנייה של אירוע push:

1. בממשק האינטרנט של Secure Source Manager, עוברים למאגר.

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

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

כדי לראות את סטטוס הבנייה של אירוע בקשת משיכה:

1. בממשק האינטרנט של Secure Source Manager, לוחצים על Pull requests.

2. לוחצים על בקשת המשיכה שרוצים לראות.

   אם הבנייה הופעלה על ידי בקשת המשיכה, יופיע קטע עם הכותרת All checks were successful (כל הבדיקות עברו בהצלחה) או Some checks reported warnings (חלק מהבדיקות הציגו אזהרות).

פתרון בעיות

כדי למצוא שיטות לאבחון ולפתרון שגיאות ב-Cloud Build כשמתחברים ל-Secure Source Manager, אפשר לעיין במאמר קובץ ההפעלה לא מפעיל את ה-build.

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

• איך צופים בתוצאות של בנייה ב-Cloud Build
• איך פותרים בעיות שקשורות לבנייה