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

טריגר של 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). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק 'שימוש בשירות'' (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. אפשר לציין את האזור של המאגר הפרטי בקובץ ההגדרות של ה-build, או להשתמש במאגר ברירת המחדל הגלובלי אם לא מציינים מאגר פרטי.

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

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

      • 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 בקבצים שהמערכת מתעלמת מהם כדי להתעלם מ-README.md בכל ספרייה, וציינתם src/* בקבצים שנכללים כדי להתחיל בנייה בשינויים בכל קובץ בתיקייה 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 להגדרה.

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

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

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

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

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

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

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

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

  5. לוחצים על יצירה כדי לשמור את טריגר הבנייה.

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 למאגרי המידע. הדגל הזה נתמך בגרסאות build ממאגרי GitHub וממאגרי GitHub Enterprise.

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

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

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

בדיקת טריגר לפיתוח גרסת 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 לא מבצע checkout של ענפים אחרים או היסטוריה אחרת. הפעולה הזו מתבצעת כדי לייעל את התהליך, כך שהגרסאות לא צריכות להמתין לאחזור של כל המאגר וההיסטוריה רק כדי ליצור קומיט יחיד.

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

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

מידע נוסף על git fetch זמין בהפניה ל-Git. הוראות לכתיבת קובץ תצורת build מופיעות במאמר סקירה כללית על תצורת 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 הוא הנתיב של הטריגר שרוצים לייבא.

טריגר הבנייה עודכן.