יצירה וניהול של טריגרים לבנייה

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

בדף הזה מוסבר איך להתחבר למאגרי קוד מקור כמו GitHub ו-Bitbucket, ואיך ליצור טריגרים של build כדי לבצע build של הקוד במאגרים.

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

כדי לוודא שלחשבון יש את ההרשאות שנדרשות ליצירה ולניהול של טריגרים לבנייה, צריך לבקש מהאדמין להקצות לחשבון את תפקיד ה-IAM‏ Cloud Build Editor (roles/cloudbuild.builds.editor) בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

בנוסף, צריך לבצע את הפעולות הבאות:

  • מפעילים את Cloud Build API, אם הוא עדיין לא מופעל.

    תפקידים שנדרשים להפעלת ממשקי API

    כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

    להפעלת ה-API

  • מוודאים שיש לכם קוד מקור ב-Cloud Source Repositories, ב-GitHub או ב-Bitbucket.
  • מוודאים שיש לכם Dockerfile או קובץ הגדרות של Cloud Build.

קישור למאגרי קוד מקור

כדי לבנות את הקוד במאגר, קודם צריך לחבר את Cloud Build למאגר המקור. מאגרי הקוד שלכם ב-Cloud Source Repositories מחוברים ל-Cloud Build כברירת מחדל. אתם יכולים ליצור טריגרים ישירות למאגרים שלכם ב-Cloud Source Repositories בלי להתחבר אליהם באופן ידני.

אם אתם מחברים מאגר חיצוני, כמו מאגר שמתארח ב-GitHub או ב-Bitbucket, תצטרכו הרשאות אדמין במאגר כדי לחבר אותו ל-Cloud Build בפעם הראשונה. לא נדרשות הרשאות אדמין כדי ליצור טריגרים במאגר שכבר מקושר ל-Cloud Build.

כדי להתחבר ל-GitHub או ל-Bitbucket:

  1. פותחים את הדף Triggers במסוף Google Cloud .

    פתיחת הדף 'טריגרים'

  2. בסרגל הכלים של מסוף Google Cloud , בוחרים את Google Cloud הפרויקט.

  3. לוחצים על Connect Repository (קישור מאגר).

  4. בתפריט הנפתח אזור, בוחרים את האזור שבו רוצים ליצור את הטריגר.

  5. בוחרים את המאגר שבו מאוחסן קוד המקור.

    אם בוחרים באפשרות GitHub (mirrored) או Bitbucket (mirrored) כמאגר המקור, Cloud Build משכפל את המאגר ב-Cloud Source Repositories ומשתמש במאגר המשוכפל לכל הפעולות שלו.

  6. לוחצים על Continue.

  7. מאמתים את הזהות שלכם במאגר המקור באמצעות שם המשתמש והסיסמה.

  8. בוחרים מאגר מרשימת המאגרים הזמינים ולוחצים על Connect (קישור).

    במאגרים חיצוניים, כמו GitHub ו-Bitbucket, צריכות להיות לכם הרשאות ברמת הבעלים בפרויקט Google Cloud שאתם עובדים איתו.

  9. לוחצים על Create a trigger כדי להמשיך ליצור טריגר לפיתוח גרסאות build כדי להפוך את הפיתוח של גרסאות build לקוד המקור במאגר לאוטומטי, או לוחצים על Done.

יצירת טריגר לפיתוח גרסת Build

כדי ליצור טריגר לפיתוח גרסת Build:

המסוף

  1. פותחים את הדף Triggers במסוף Google Cloud .

    פתיחת הדף Triggers

  2. בסרגל הכלים של מסוף Google Cloud , בוחרים את Google Cloud הפרויקט.

  3. לוחצים על Create trigger (יצירת ביטוי להפעלה).

  4. מזינים את הגדרות הטריגר הבאות:

    • שם: מזינים שם לטריגר.

    • אזור: בוחרים את האזור של הטריגר.

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

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

    • תיאור (אופציונלי): מזינים תיאור לטריגר.

    • אירוע: בוחרים את אירוע המאגר להפעלת הטריגר.

      • Push to a branch: מגדירים את הטריגר להתחלת בנייה של קומיטים בענף מסוים.

      • Push new tag: מגדירים את הטריגר להתחלת בנייה בביצועי Commit שמכילים תג מסוים.

      • בקשת משיכה: מגדירים את הטריגר להתחלת בנייה בהתחייבויות לבקשת משיכה.

    • מקור: בוחרים באפשרות דור ראשון או דור שני כמקור. אפשר לקשר מאגרים מ-GitHub ומ-GitHub Enterprise רק כשבוחרים באפשרות דור שני כמקור. מידע נוסף זמין במאמר מאגרי Cloud Build.

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

      • Branch או Tag: מציינים ביטוי רגולרי עם ערך הענף או התג להתאמה. אי אפשר להשתמש בקו נטוי (/) בתגים. מידע נוסף על תחביר מקובל של ביטויים רגולריים זמין במאמר בנושא תחביר RE2.

        כשמריצים את ה-build, ‏ Cloud Build מעתיק את התוכן של המאגר אל /workspace, ספריית העבודה שמוגדרת כברירת מחדל ב-Cloud Build. מידע נוסף על ספריות עבודה

        כדי לאפשר רק בנייה ממקורות ספציפיים, מגדירים מדיניות ארגונית לשילובים מותרים (constraints/cloudbuild.allowedIntegrations) כדי לדחות אינטראקציה עם המקור שהוגדר בטריגר. מדיניות הארגון מבטלת את הטריגר וה-build לא מופעל. מידע נוסף זמין במאמר בנושא שערים לבנייה לפי מדיניות הארגון.

    • קבצים כלולים (אופציונלי): שינויים שמשפיעים על לפחות אחד מהקבצים האלה יפעילו בנייה. אפשר להשתמש במחרוזות glob כדי לציין כמה קבצים עם תווים כלליים לחיפוש. התווים הכלליים לחיפוש שבהם אפשר להשתמש הם התווים שנתמכים על ידי Go Match,‏ ** והחלפה.

    • קבצים שהמערכת מתעלמת מהם (אופציונלי): שינויים שמשפיעים רק על קבצים שהמערכת מתעלמת מהם לא יפעילו בנייה. אפשר להשתמש במחרוזות glob כדי לציין כמה קבצים עם תווים כלליים לחיפוש. התווים הכלליים לחיפוש שניתן להשתמש בהם כוללים את התווים שנתמכים על ידי Go Match,‏ ** והחלפה.

      אם מציינים קובץ גם בIncluded files וגם בIgnored files, שינויים בקובץ הזה לא יפעילו בנייה. נניח שציינתם את **/README.md בIgnored files כדי להתעלם מ-README.md בכל ספרייה, וציינתם את src/* בIncluded files כדי להתחיל בנייה בשינויים בכל קובץ בתיקייה src/. אם עכשיו תבצעו שינוי ב-src/README.md, ‏ Cloud Build לא יתחיל ב-Build. בכל פעם שאתם מעבירים שינוי למקור, Cloud Build בודק את הקבצים שהשתנו כדי לראות אם יש קבצים כלולים או קבצים שהמערכת מתעלמת מהם, וכך קובע אם צריך להפעיל בנייה:

      • אם מעבירים שינוי למאגר ב-branch קיים,‏ Cloud Build בודק את הקבצים ששונו בין הקומיט שהועבר לבין הקומיט שאליו הצביע ה-branch בעבר.
      • אם המאגר שלכם הוא Cloud Source Repository ואתם דוחפים שינוי לענף שנוצר לאחרונה, Cloud Build מתייחס לכל הקבצים במאגר כאל קבצים שעברו שינוי.
      • אם מוחקים הסתעפות, Cloud Build לא מתחיל בנייה.

    • Configuration (תצורה): בוחרים את קובץ תצורת ה-build שנמצא במאגר המרוחק או יוצרים קובץ תצורת build מוטבע לשימוש ב-build.

      • סוג: בוחרים את סוג ההגדרה שרוצים להשתמש בו ב-build.
        • קובץ תצורת Cloud Build (yaml או json): משתמשים בקובץ תצורת build להגדרה.
        • ‫Dockerfile: משתמשים ב-Dockerfile להגדרה.
        • ‫Buildpacks: משתמשים ב-buildpacks להגדרה.

      • מיקום: מציינים את המיקום של ההגדרה.

        • מאגר: אם קובץ התצורה נמצא במאגר המרוחק, צריך לציין את המיקום של קובץ התצורה של ה-build, של הספרייה Dockerfile או של ספריית ה-buildpacks. אם סוג buildconfig הוא Dockerfile או buildpack, צריך לציין שם לקובץ האימג' שנוצר, ואפשר גם לציין זמן קצוב לתהליך ה-build. אחרי שמזינים את שם התמונה של Dockerfile או של buildpack, מוצגת תצוגה מקדימה של הפקודה docker build או pack שה-build יבצע.
        • משתני סביבה של Buildpack (אופציונלי): אם בחרתם באפשרות buildpacks כסוג התצורה, לוחצים על הוספת משתנה סביבה של pack כדי לציין את משתני הסביבה והערכים של ה-buildpack. מידע נוסף על משתני סביבה של buildpack זמין במאמר משתני סביבה.

        • בתוך השורה: אם בחרתם באפשרות קובץ הגדרות של Cloud Build (yaml או json), תוכלו לציין את הגדרות ה-build בתוך השורה. לוחצים על Open Editor כדי לכתוב את קובץ ההגדרות של ה-build בGoogle Cloud מסוף באמצעות תחביר YAML או JSON. לוחצים על Done (סיום) כדי לשמור את הגדרות ה-build.

    • שימוש במאגר פרטי: השדה הזה מופיע אם בחרתם באפשרות Dockerfile בשדה הגדרה. מסמנים את התיבה הזו אם מריצים את הבנייה במאגר פרטי.

    • מאגר פרטי: אם בחרתם באפשרות שימוש במאגר פרטי, מציינים את שם המשאב של המאגר הפרטי בפורמט projects/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/WORKERPOOL_ID.

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

    • אישור (אופציונלי): מסמנים את התיבה כדי לדרוש אישור לפני הפעלת ה-build.

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

  5. לוחצים על יצירה כדי לשמור את טריגר לפיתוח גרסת Build.

gcloud

כדי ליצור טריגר אם קוד המקור נמצא ב-Cloud Source Repositories:

    gcloud builds triggers create cloud-source-repositories \
    --repo=REPO_NAME \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval

כאשר:

  • ‫REPO_NAME הוא שם המאגר.
  • ‫BRANCH_PATTERN הוא שם הענף במאגר שבו רוצים להפעיל את ה-build.
  • ‫TAG_PATTERN הוא שם התג במאגר שמשמש להפעלת ה-build.
  • ‫BUILD_CONFIG_FILE הוא הנתיב לקובץ התצורה של ה-build.
  • ‫SERVICE_ACCOUNT הוא חשבון השירות שבו יש להשתמש להפעלת פעולות ולביצוע פעולות build.
  • אופציונלי: כדי להגדיר את הטריגר כך שיידרש אישור, מגדירים את הדגל --require-approval.

רשימה מלאה של הדגלים מופיעה במאמר gcloudיצירת טריגרים ל-Cloud Source Repositories.

כדי ליצור טריגר אם קוד המקור נמצא ב-GitHub:

    gcloud builds triggers create github \
    --name=TRIGGER_NAME \
    --region=REGION \
    --repo-name=REPO_NAME \
    --repo-owner=REPO_OWNER \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval
    --include-logs-with-status

כאשר:

  • ‫REGION הוא האזור של הטריגר.
  • ‫REPO_NAME הוא שם המאגר.
  • ‫REPO_OWNER הוא שם המשתמש של בעל המאגר.
  • ‫BRANCH_PATTERN הוא שם הענף במאגר שבו רוצים להפעיל את ה-build.
  • ‫TAG_PATTERN הוא שם התג במאגר שמשמש להפעלת ה-build.
  • ‫BUILD_CONFIG_FILE הוא הנתיב לקובץ התצורה של ה-build.
  • ‫SERVICE_ACCOUNT הוא חשבון השירות שבו יש להשתמש להפעלת פעולות ולביצוע פעולות build.
  • אופציונלי: --require-approval הוא הדגל שצריך לכלול כדי להגדיר את הטריגר כך שיידרש אישור.
  • אופציונלי: --include-logs-with-status הוא דגל שאפשר לציין כדי להציג יומני build למאגרי המידע. הדגל הזה נתמך ב-builds ממאגרי GitHub וממאגרי GitHub Enterprise.

רשימה מלאה של הדגלים זמינה במאמר בנושא gcloud יצירת טריגרים ל-GitHub.

אחרי שמריצים את הפקודה gcloud כדי ליצור טריגר באמצעות Cloud Source Repositories או GitHub, אמור להופיע פלט שדומה לזה שמופיע בדוגמה הבאה:

  NAME         CREATE_TIME                STATUS
  trigger-001  2019-10-30T20:45:03+00:00

בדיקת טריגר לפיתוח גרסת Build

כדי לבדוק טריגר לפיתוח גרסת Build באופן ידני:

  1. פותחים את הדף Triggers במסוף Google Cloud .

    פתיחת הדף 'טריגרים'

  2. בסרגל הכלים של מסוף Google Cloud , בוחרים את Google Cloud הפרויקט.

  3. מחפשים את הטריגר ברשימה ולוחצים על הפעלה.

דילוג על טריגר לפיתוח גרסת Build

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

במקרים כאלה, אפשר לכלול את [skip ci] או [ci skip] בהודעת הקומיט, ולא תופעל בנייה.

אם רוצים להריץ build על הקומיט הזה מאוחר יותר, משתמשים בלחצן Run בדף Triggers.

הכללת היסטוריית המאגר ב-build

כדי לבנות את המקור במאגר Git, ‏ Cloud Build מבצע שיבוט (clone) שטחי של המאגר. כלומר, רק הקומיט היחיד שהתחיל את הבנייה נבדק בסביבת העבודה לצורך הבנייה. ‫Cloud Build לא מאחזר ענפים אחרים או היסטוריה. הסיבה לכך היא יעילות – כדי שלא יהיה צורך להמתין עד לאחזור המאגר וההיסטוריה במלואם רק כדי לבנות קומיט יחיד.

אם רוצים לכלול עוד מההיסטוריה של מאגר הקוד ב-Build, מוסיפים שלב build לקובץ התצורה של ה-Build כדי לבטל את ה-shallow clone. לדוגמה:

steps:
- name: gcr.io/cloud-builders/git
  args: ['fetch', '--unshallow']
...

מידע נוסף על git fetch זמין בהפניה ל-Git. הוראות לכתיבת קובץ תצורת build זמינות במאמר סקירה כללית על תצורת build.

שליחה מחדש של בילד לאישור

אם ה-build נדחה, אפשר לשלוח אותו מחדש לאישור באופן הבא במסוף Google Cloud :

  1. פותחים את הדף Cloud Build History במסוף Google Cloud .

    פתיחת הדף 'היסטוריה' של Cloud Build

  2. לוחצים על מזהה הגרסה של הגרסה שרוצים לשלוח מחדש לאישור.

  3. כדי לשלוח מחדש את הגרסה לבדיקה, לוחצים על Rebuild (בנייה מחדש) בחלק העליון של הדף.

הגרסה תתחיל להיבנות כשמשתמש עם הרשאות יאשר את הבנייה. מידע נוסף על אישורים ב-Cloud Build זמין במאמר בנושא הגבלת גישה ל-builds באמצעות אישור.

עדכון טריגר לפיתוח גרסת Build

המסוף

  1. פותחים את הדף Triggers במסוף Google Cloud .

    פתיחת הדף Build triggers

  2. בסרגל הכלים של מסוף Google Cloud , בוחרים את Google Cloud הפרויקט.

  3. מחפשים את השורה עם הטריגר שרוצים לעדכן.

  4. לוחצים על התפריט (שלוש נקודות אנכיות) בקצה השמאלי של השורה.

  5. לוחצים על עריכה.

gcloud

כדי לעדכן טריגר:

  1. מייצאים את הטריגר שרוצים לעדכן:

     gcloud beta builds triggers export TRIGGER_NAME --destination=EXPORT_PATH

    כאשר:

    • ‫TRIGGER_NAME הוא השם של הטריגר.
    • ‫EXPORT_PATH הוא הנתיב שאליו רוצים לייצא את הטריגר. לדוגמה, אפשר לציין את הנתיב כ-examples/trigger.yaml. שימו לב ששם הקובץ של הטריגר צריך להסתיים בסיומת YAML.

  2. פותחים את הקובץ שמכיל את הטריגר שייצאתם.

    הקובץ ייראה בערך כך:

     createTime: '2022-05-26T21:56:11.830784153Z'
 filename: cloudbuild.yaml
 github:
   name: cloud-build-example
   owner: main
   push:
     branch: master
 id: 86201062-3b14-4b6a-a2fb-4ee924e8b1dd
 # remove field name and value to not show build logs
 includeBuildLogs: INCLUDE_BUILD_LOGS_WITH_STATUS
 name: trigger-001

  3. עורכים את הקובץ באופן ידני כדי לעדכן את הטריגר.

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

  4. שומרים את הקובץ.

  5. מייבאים את הטריגר:

     gcloud builds triggers import --source=IMPORT_PATH

    כאשר:

    • ‫IMPORT_PATH הוא הנתיב של הטריגר שרוצים לייבא.

טריגר לפיתוח גרסת Build עודכן.