‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

ביצוע אוטומציה של גרסאות build בתגובה לאירועי webhook

ב-Cloud Build אפשר להגדיר טריגרים של webhook כדי לאמת ולקבל אירועי webhook נכנסים. האירועים האלה, שנשלחים לכתובת URL מותאמת אישית, מאפשרים לכם לחבר מערכות חיצוניות ופלטפורמות לניהול קוד מקור, כמו Bitbucket.com,‏ Bitbucket Server או GitLab, ישירות ל-Cloud Build.

בטריגרים של תגובה לפעולה מאתר אחר, אתם יכולים לציין תצורת build מוטבעת במקום מאגר מקור. ההגדרה הזו מאפשרת לכם לשלוט בפעולות של Git ובתהליך ה-build. כדי להפוך את ה-builds לאוטומטיים באירועים של מאגרים, אתם יכולים להשתמש בטריגרים של מאגרים ב-Cloud Build, שמשתלבים ישירות עם ספקים כמו GitHub ו-GitLab.

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

בדף הזה מוסבר איך ליצור טריגרים של תגובה לפעולה מאתר אחר (webhook) כדי להפוך את גרסאות ה-build לאוטומטיות בתגובה לאירועים של תגובה לפעולה מאתר אחר.

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

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

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

כדי להשתמש בפקודות של gcloud בדף הזה, צריך להתקין את Google Cloud CLI.

הערה: אם התקנתם בעבר את ה-CLI של gcloud, צריך לוודא שפועלת אצלכם הגרסה העדכנית ביותר של gcloud components update.
אם הטריגר של ה-webhook משתמש במאגר של Cloud Build כמקור, ודאו שאתם מכירים את המאגרים של Cloud Build.

יצירת טריגרים של תגובה לפעולה מאתר אחר (webhook)

המסוף

כדי ליצור טריגר של webhook באמצעות מסוף Google Cloud :

פותחים את הדף Triggers:

פותחים את הדף טריגרים לפיתוח גרסת Build
בוחרים את הפרויקט בחלק העליון של הדף ולוחצים על פתיחה.
לוחצים על Create trigger (יצירת טריגר).
מזינים את הגדרות הטריגר הבאות:
- שם: שם לטריגר.
- ‫Region: בוחרים את האזור של הטריגר.
  - אם קובץ תצורת ה-build שמשויך לטריגר מציין מאגר פרטי, Cloud Build משתמש במאגר הפרטי כדי להריץ את ה-build. במקרה כזה, האזור שאתם מציינים בטריגר צריך להתאים לאזור שבו יצרתם את המאגר הפרטי.
  - אם בקובץ תצורת ה-build שמשויך לטריגר לא מצוין מאגר פרטי, Cloud Build משתמש במאגר ברירת המחדל כדי להריץ את ה-build באותו אזור של הטריגר.
- תיאור (אופציונלי): תיאור של הטריגר.
- אירוע: בוחרים באפשרות אירוע לפעולה מאתר אחר (webhook) כדי להגדיר את הטריגר להפעלת גרסאות build בתגובה לאירועים נכנסים לפעולה מאתר אחר (webhook).
- ‫Webhook URL: משתמשים ב-webhook URL כדי לאמת אירועי webhook נכנסים. כדי לאמת אירועים נכנסים של תגובה לפעולה מאתר אחר (webhook), צריך סוד. אתם יכולים ליצור סוד חדש או להשתמש בסוד קיים. הסוד הזה נפרד מהסוד שמשויך למפתח ה-SSH.
  
  כדי ליצור סוד:
  1. בוחרים באפשרות Use a new secret (generated by Cloud Build).
  2. לוחצים על Create Secret.
    
    תיפתח תיבת הדו-שיח Create a webhook secret.
  3. בשדה Secret name, מזינים שם לסוד.
  4. לוחצים על Create secret כדי לשמור את הסוד, שייווצר ויישמר באופן אוטומטי ב-Secret Manager.
  כדי להשתמש בסוד קיים:
  1. בוחרים באפשרות Use an existing secret or create your own.
  2. בשדה Secret, בוחרים בתפריט הנפתח את שם הסוד שרוצים להשתמש בו, או פועלים לפי ההוראות להוספת סוד לפי מזהה משאב.
  3. בשדה Secret version, בוחרים את גרסת הסוד מהתפריט הנפתח.
    
    אם אתם משתמשים בסוד קיים, יכול להיות שתצטרכו להקצות באופן ידני את התפקיד "גישה לסודות ב-Secret Manager" לחשבון השירות של Cloud Build, ‏ service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. למידע נוסף, קראו את המאמר הקצאת תפקיד Secret Manager לחשבון השירות.
    
    אחרי שיוצרים או בוחרים את הסוד, מופיעה תצוגה מקדימה של כתובת ה-URL של ה-webhook. כתובת ה-URL תכיל מפתח API שנוצר על ידי Cloud Build ואת הסוד שלכם. אם Cloud Build לא מצליח לאחזר את מפתח ה-API, אתם יכולים להוסיף אותו ידנית לכתובת ה-URL או לקבל מפתח API אם עדיין אין לכם.
    
    אתם יכולים להשתמש בכתובת ה-URL כדי להפעיל אירוע webhook על ידי שליחת בקשת HTTP באמצעות השיטה POST.
    
    אחרי שתבצעו את השלבים האלה, התפקיד Secret Manager Secret Accessor יוקצה באופן אוטומטי לסוכן השירות של Cloud Build,‏ service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. אם התפקיד הזה לא נוסף אוטומטית לסוכן השירות, צריך לבצע את השלבים שמפורטים בקטע הקצאת תפקיד Secret Manager לחשבון השירות.
- ‫Source (אופציונלי): אם אתם מציינים תצורת build מוטבעת, אתם לא צריכים לציין מקור. אם לא, מבצעים את הפעולות הבאות:
  - Repository generation: בוחרים באפשרות 2nd generation.
  - ‫Repository: בוחרים את המאגר שממנו רוצים לבצע את ה-build. האזור של המאגר צריך להיות זהה לאזור של הטריגר.
  - ‫Branch או Tag: מציינים ביטוי רגולרי עם ערך ההתאמה של הענף או התג. למידע על תחביר מקובל של ביטויים רגולריים, ראו תחביר RE2.
  - Comment control: אם בחרתם באפשרות Pull request בתור Event, בחרו אחת מהאפשרויות הבאות כדי לקבוע אם הטריגר יפעיל build באופן אוטומטי:
    
    אזהרה: כל משתמש עם הרשאת קריאה למאגר יכול לשלוח בקשת משיכה, שעשויה להריץ גרסה שכוללת שינויים בקוד המקור בבקשת המשיכה. כדי להשבית את ההתנהגות הזו, מומלץ להשתמש באישורים ידניים כדי להגביל את ה-builds כשמבצעים בקשות משיכה במאגרים ציבוריים. מידע נוסף על הרשאות של טריגרים בזמן ה-build
    - נדרש, למעט לבעלים ולשותפי עריכה: כשבקשת משיכה נוצרת או מתעדכנת על ידי בעלים או שותף עריכה של מאגר, ה-builds מופעלים באופן אוטומטי. אם גורם חיצוני יוזם את הפעולה, ה-builds יופעלו רק אחרי שבעלים או שותף עריכה יגיבו /gcbrun בבקשת ה-pull.
    - נדרש: כשבקשת משיכה נוצרת או מתעדכנת על ידי כל אחד מהתורמים, גרסאות build מופעלות רק אחרי שבעלים או שותף עריכה מגיבים /gcbrun לבקשת המשיכה. ה-builds מופעלים בכל פעם שמתבצע שינוי בבקשת משיכה.
    - Not required: כשבקשת משיכה נוצרת או מתעדכנת על ידי כל אחד מהתורמים, גרסאות ה-build מופעלות באופן אוטומטי.
- ‫Configuration: בוחרים את קובץ תצורת ה-build שנמצא במאגר המרוחק, או יוצרים קובץ תצורת build מוטבע לשימוש ב-build. אם לא ציינתם מאגר מקור, אתם צריכים לבחור קובץ תצורה של build בתוך השורה כאפשרות התצורה:
  - Type: בוחרים את סוג ההגדרה שבה רוצים להשתמש ב-build.
    - קובץ תצורה של Cloud Build (בפורמט yaml או json): משתמשים בקובץ תצורת build.
    - ‫Dockerfile: שימוש ב-Dockerfile להגדרה.
    - ‫Buildpacks: שימוש ב-buildpacks להגדרה.
  - מיקום: המיקום של ההגדרה.
    - ‫Repository: אם קובץ התצורה נמצא במאגר המרוחק, צריך לציין את המיקום של קובץ תצורת ה-build, הספרייה Dockerfile או ספריית ה-buildpacks. אם סוג תצורת ה-build הוא Dockerfile או buildpack, תצטרכו לתת שם לקובץ האימג' שנוצר, ואם תרצו, גם זמן קצוב לתפוגה של ה-build. אחרי שמזינים את שם קובץ האימג' של Dockerfile או של buildpack, מוצגת תצוגה מקדימה של הפקודה docker build או pack שה-build יריץ.
    - ‫Buildpack environment variables (אופציונלי): אם בחרתם באפשרות buildpacks כסוג ההגדרה, לוחצים על Add pack environment variable כדי לציין את משתני הסביבה והערכים של ה-buildpack. למידע נוסף על משתני סביבה של buildpack, ראו משתני סביבה.
    - ‫Inline: אם בחרתם באפשרות Cloud Build configuration file (yaml or json), אתם יכולים לציין את קובץ תצורת ה-build בתוך השורה. לוחצים על Open Editor כדי לכתוב את קובץ תצורת ה-build במסוףGoogle Cloud באמצעות תחביר YAML או JSON. לוחצים על Done כדי לשמור את תצורת ה-build.
      
      הערה: אין תמיכה בהגדרת build מוטבעת ב-Dockerfile או ב-buildpacks.
  בדוגמה הבאה, קובץ התצורה של ה-build בתוך השורה מתעד את הפקודה echoes "hello world":
```
 steps:
 - name: 'ubuntu'
   args: ['echo', 'hello world']
```
- החלפות (אופציונלי): אם בחרתם בקובץ תצורת ה-build כאפשרות לתצורת ה-build, או אם יצרתם קובץ תצורת build מוטבע, אתם יכולים להשתמש בשדה הזה כדי להגדיר משתני החלפה ספציפיים לטריגר. אפשר גם לקבל נתונים באמצעות קישורי מטען ייעודי (payload) כשמגדירים ערכים של משתני החלפה.
- מסננים (אופציונלי): אתם יכולים ליצור כלל בתוך טריגר שקובע אם הטריגר יריץ גרסה build על סמך משתני ההחלפה.
לוחצים על Create כדי ליצור את הטריגר לפיתוח גרסת ה-Build.

gcloud

כדי ליצור טריגר של תגובה לפעולה מאתר אחר (webhook):

gcloud builds triggers create webhook \
  --trigger-config=TRIGGER_CONFIG_PATH \
  --name=TRIGGER_NAME \
  --description=DESCRIPTION \
  --region=REGION \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --service-account=SERVICE_ACCOUNT \ 
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \ 
  --build-config=PATH_TO_BUILD_CONFIG \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --dockerfile=DOCKERFILE \
  --dockerfile-dir=DOCKERFILE_DIR \
  --dockerfile-image=DOCKERFILE_IMAGE \
  --tag=TAG_NAME \
  --branch=BRANCH_NAME \
  --substitutions=_SUB_ONE=SUBSTITUTION \
  --subscription-filter=FILTER \
  --require-approval

כאשר:

‫TRIGGER_CONFIG_PATH הוא הנתיב לקובץ תצורה של טריגר. אם משתמשים בקובץ תצורה של טריגר, השדות name,‏ description,‏ region,‏ secret,‏ service-account,‏ subscription-filter ו-substitution צריכים להישאר לא מוגדרים. מידע נוסף זמין במאמרי העזרה של Cloud Build בנושא BuildTrigger.
‫TRIGGER_NAME הוא שם הטריגר.
‫DESCRIPTION (אופציונלי) הוא תיאור של הטריגר.
‫REGION הוא האזור של הטריגר. הערך הזה חייב להיות אזור שהוא לא "global".
‫SECRET_NAME הוא שם הסוד שמאוחסן ב-Secret Manager.
‫SECRET_VERSION היא הגרסה שמשויכת לסוד שמאוחסן ב-Secret Manager.
‫SERVICE_ACCOUNT הוא חשבון השירות שמשמש להרצת כל הפעולות שבשליטת המשתמש שקשורות לטריגר לפיתוח גרסת ה-Build. אם לא מגדירים חשבון שירות, Cloud Build משתמש בחשבון השירות שמוגדר כברירת מחדל ב-Cloud Build.
‫PROJECT_ID הוא מזהה הפרויקט ב- Google Cloud .
‫CONNECTION_NAME הוא השם של החיבור למארח.
‫REPO_NAME הוא שם המאגר.
‫PATH_TO_BUILD_CONFIG הוא הנתיב לקובץ תצורה של build. השתמשו בפרמטר הזה אם הטריגר מתייחס לקובץ תצורה של build במאגר של Cloud Build. אם מגדירים את הפרמטר הזה, אי אפשר להגדיר inline-config או להשתמש בפרמטרים של קובץ Docker.
‫PATH_TO_INLINE_BUILD_CONFIG הוא הנתיב לתצורת build מוטבעת. השתמשו בפרמטר הזה אם הטריגר מתייחס לקובץ תצורה מקומי של build. אם מגדירים את הפרמטר הזה, אי אפשר להגדיר build-config או להשתמש בפרמטרים של קובץ Docker.
‫DOCKERFILE הוא הנתיב לקובץ Docker. השתמשו בפרמטר הזה אם הטריגר מתייחס לקובץ Docker. אם מגדירים פרמטרים של קובץ Docker, אי אפשר להגדיר build-config או inline-config.
‫DOCKERFILE_DIR היא הספרייה של קובץ ה-Dockerfile.
‫DOCKERFILE_IMAGE הוא השם של קובץ האימג' של Docker שנוצר על ידי Cloud Build.
‫BRANCH_NAME הוא שם ההסתעפות, אם רוצים להגדיר את הטריגר ל-build בהסתעפות. אם מגדירים את הפרמטר הזה, אי אפשר להגדיר tag.
‫TAG_NAME הוא שם התג, אם רוצים להגדיר את הטריגר כך שיתבסס על תג. אם מגדירים את הפרמטר הזה, אי אפשר להגדיר branch.
‫SUBSTITUTION (אופציונלי) הם פרמטרים שיוחלפו במפרט ה-build. לדוגמה, _SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)'.
‫FILTER (אופציונלי) הוא ביטוי סינון של CEL לטריגר, כמו '_SUB_ONE == "prod"'.
(אופציונלי) כש---require-approval מופיע בפקודה, Cloud Build דורש אישור ידני ל-builds שמופעלים.

הפעלת אירוע webhook

כדי להפעיל אירוע של תגובה לפעולה מאתר אחר, משתמשים בפקודה הבאה:

curl -X POST -H "Content-type: application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}&trigger=${TRIGGER_NAME}&projectId=${PROJECT_ID}" -d "{}"

(אופציונלי) הקצאת תפקיד ב-Secret Manager לחשבון השירות

כשמגדירים את הסוד במהלך היצירה של הטריגר ל-webhook, ברוב המקרים Cloud Build מקצה באופן אוטומטי את התפקיד Secret Manager Secret Accessor לחשבונות השירות שצריכים את התפקיד הזה. עם זאת, אם אתם משתמשים בסוד קיים, יכול להיות שתצטרכו גם להקצות באופן ידני את התפקיד "מנהל גישה לסודות ב-Secret Manager" לחשבון השירות של Cloud Build:

פותחים את הדף IAM במסוף Google Cloud :

פתיחת הדף IAM
אופציונלי: כדי לראות את החשבונות שסופקו על ידי Google, מסמנים את התיבה Include Google-provided role grants.
שימו לב לחשבון השירות של ה-build שאתם רוצים להקצות לו את התפקיד.
פותחים את הדף Secret Manager במסוף Google Cloud :

פותחים את הדף Secret Manager.
לוחצים על שם הסוד.

יוצג הדף Secret details.
1. לוחצים על הכרטיסייה Permissions.
2. לוחצים על הענקת גישה.
  
  יופיע החלונית הענקת גישה.
3. בקטע Add Principals, מוסיפים את כתובת האימייל שמשויכת לחשבון השירות של ה-build.
4. בקטע Assign roles, בוחרים באפשרות Secret Manager > Secret Manager Secret Accessor.
5. לוחצים על Save.

(אופציונלי) קבלת מפתח API

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

כדי לקבל מפתח API:

פותחים את הדף Credentials במסוף Google Cloud :

לדף Credentials
לוחצים על יצירת פרטי כניסה.
לוחצים על מפתח API.

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

במאמר החלת הגבלות על מפתחות API מוסבר איך להגביל את המפתח.