חיבור ל-Cloud Build

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

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

1. יצירת מופע של Secure Source Manager
2. יצירת מאגר Secure Source Manager
3. הגדרת חשבון שירות שצוין על ידי המשתמש ב-Cloud Build.

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

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

• Secure Source Manager Repository Writer (roles/securesourcemanager.repoWriter) on your repository
• ‫Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) במופע Secure Source Manager

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

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

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

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

כדי ליצור קובצי build ולקבל את סטטוס ה-build מ-Cloud Build, צריך להעניק לסוכן השירות של Secure Source Manager‏ (service-PROJECT-NUMBER@gcp-sa-sourcemanager.iam.gserviceaccount.com) את התפקידים הבאים בניהול זהויות והרשאות גישה (IAM):

• התפקיד Cloud Build Editor‏ (roles/cloudbuild.builds.editor) בפרויקט שבו הפעלתם את Cloud Build.
• התפקיד משתמש בחשבון שירות (roles/iam.serviceAccountUser) בחשבון השירות של Cloud Build, או בפרויקט שבו נוצר חשבון השירות של Cloud Build.
• אם הפרויקט שבו הפעלתם את Cloud Build שונה מהפרויקט שבו הפעלתם את Secure Source Manager, צריך להעניק את התפקיד Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) בפרויקט Cloud Build.
• אם גרסאות ה-build פועלות במאגרי עובדים, צריך להעניק לחשבון השירות של Secure Source Manager את התפקיד Cloud Build WorkerPool User (roles/cloudbuild.workerPoolUser) בפרויקט Cloud Build.

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

• התפקיד Secure Source Manager Instance Accessor ‏(roles/securesourcemanager.instanceAccessor) במופע Secure Source Manager.
• הרשאה Secure Source Manager Repository Reader במאגר Secure Source Manager שרוצים לקשר ל-Cloud Build.

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

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

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

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

יצירת קובץ תצורת 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 עם הנתיב לקובץ תצורת ה-build של 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 בגלל המגבלות שלו.

   • ‫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 כשהשינויים בבקשת משיכה יימשכו מ-Git.

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

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

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

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

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

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

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

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

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

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

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

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

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

פתרון בעיות

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

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

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