הגדרת webhooks

בדף הזה מוסבר איך להגדיר ווּבְּהוּקים ב-Secure Source Manager.

‫Webhooks הם בקשות HTTP שמופעלות על ידי אירוע ב-Secure Source Manager ונשלחות לכתובת URL שהמשתמש מציין.

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

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

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

כדי לקבל את ההרשאות שדרושות ליצירת וווב-הוקים, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

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

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

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

הגדרת webhook

המסוף

  1. בממשק האינטרנט של Secure Source Manager, עוברים למאגר שרוצים ליצור עבורו webhook.
  2. לוחצים על הגדרות.
  3. לוחצים על Webhooks (הודעות webhook) ואז על Add webhook (הוספת הודעת webhook).

  4. בשדה Hook ID (מזהה ה-webhook), מזינים מזהה ל-webhook.

  5. בשדה כתובת URL של היעד, מזינים את כתובת ה-URL של ה-Webhook. לדוגמה, אם רוצים להפעיל build ב-Jenkins, אפשר להגדיר טריגר webhook ואז להזין כאן את כתובת ה-URL של הטריגר ב-Jenkins כדי להפעיל את ה-build ב-Jenkins.

  6. בקטע Trigger on, בוחרים באחת מהאפשרויות הבאות:

    • Push: כדי להפעיל כשמתבצעת העברה למאגר.
    • Pull request state changed: כדי להפעיל שינוי במצב של בקשת משיכה.

  7. מגדירים אימות של webhook באמצעות מחרוזת שאילתה רגישה או אימות של חשבון שירות:

    • מחרוזת שאילתה עם תוכן רגיש:

      מחרוזת השאילתה הרגישה מורכבת מהערכים key ו-secret מכתובת ה-webhook URL, כולל הקידומות key= ו-secret=. כדי להגדיר הרשאה למחרוזת שאילתה רגישה, צריך להסיר את הערכים האלה מכתובת ה-URL של ה-webhook ולהוסיף אותם לשדה מחרוזת שאילתה רגישה:

      1. מוחקים את התו ? מכתובת ה-URL של ה-webhook.
      2. מעתיקים את החלק הנותר של כתובת ה-URL, החל מ-key=.
      3. מדביקים את החלק הזה בשדה מחרוזת שאילתה רגישה.
      4. מוחקים את אותו החלק מכתובת ה-URL של ה-webhook.

      לדוגמה, אם כתובת ה-URL היא: https://cloudbuild.googleapis.com/v1/projects/my-project/triggers/test-trigger:webhook?key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=My%20Secret%20

      מחרוזת השאילתה עם המידע הרגיש תהיה: key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=My%20Secret%20

    • אימות של חשבון שירות:

      1. מוודאים שלמאגר יש חשבון שירות עם תפקידי ה-IAM שמוגדרים לאימות חשבון השירות בתפקידים נדרשים.
      2. בוחרים באפשרות Enable service account authentication.

  8. אם בחרתם באפשרות Push, תוכלו להזין רשימת היתרים לאירועי Push בשדה Branch filter.

    בשדה Branch filter נעשה שימוש בתבנית glob, ורק פעולות בענפים התואמים יפעילו טריגר לפיתוח גרסת Build. לדוגמה, ‫{main,dev} מופעל באירועי push בענפים main ו-dev. אם השדה ריק או שהערך שלו הוא *, האירועים של כל הענפים מדווחים. מידע על התחביר מופיע במאמר בנושא glob.

  9. לוחצים על Add webhook (הוספת webhook).

  10. ה-webhook מוצג בדף Webhooks.

REST

כדי ליצור webhook, מפעילים את ה-method‏ hooks.create על ידי שליחת בקשת POST לנקודת הקצה hooks. אתם יכולים לאמת את ה-webhook באמצעות מחרוזת שאילתה רגישה או אימות של חשבון שירות.

  • מחרוזת שאילתה עם תוכן רגיש

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUri": "https://${SERVICE_NAME}.app/webhook?key=${KEY}&secret=${SECRET}",
    "events": ["PUSH"]
    "sensitiveQueryString": "${SENSITIVE_QUERY_STRING_VALUE}"
  }' \
  "https://securesourcemanager.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/repositories/${REPOSITORY}/hooks?hook_id=${HOOK_ID}"

    הערך של SENSITIVE_QUERY_STRING_VALUE צריך להיות הערך של key ושל secret בכתובת ה-URL של ה-webhook. לדוגמה, אם הערך של key הוא eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf והערך של secret הוא MySecret, אז הערך של SENSITIVE_QUERY_STRING_VALUE צריך להיות key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=MySecret.

  • אימות של חשבון שירות

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUri": "https://${SERVICE_NAME}.app/webhook",
    "events": ["PUSH"],
    "serviceAccountAuth": true
  }' \
  "https://securesourcemanager.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/repositories/${REPOSITORY}/hooks?hook_id=${HOOK_ID}"

בדיקת ה-webhook

  1. בדף Webhooks (ווּבְהוּקים) ב-Secure Source Manager, לוחצים על הווב-הוק שרוצים לבדוק.

  2. גוללים לתחתית הדף ולוחצים על בדיקת המסירה.

    אירוע placeholder נוסף לתור המסירה. יכול להיות שיחלפו כמה שניות עד שהיא תופיע בהיסטוריית המשלוחים.

  3. אפשר גם להשתמש בפקודה git כדי לשלוח או למזג בקשת משיכה כדי לבדוק את ה-webhook.

  4. בודקים את הסטטוס של הבנייה או האירוע שהופעלו בהיסטוריית הבנייה של השירות שבו הגדרתם את טריגר ה-webhook.

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

החלפת משתני YAML של Cloud Build בנתוני מטען ייעודי (payload)

אם אתם משתמשים ב-webhooks כדי להתחבר ל-Cloud Build, אתם יכולים להחליף את משתני ה-YAML של Cloud Build בנתוני מטען הייעודי (payload) של webhook של Secure Source Manager.

  1. בדף Webhooks (ווּבְהוּקים) של Secure Source Manager, בקטע Recent deliveries (מסירות אחרונות), לוחצים על השורה העליונה.

    מוצגים הכותרת Request והתוכן שנשלח על ידי המטען הייעודי (payload) של ה-webhook.

  2. עוברים ללוח הבקרה של Cloud Build ולוחצים על Triggers (טריגרים).

  3. לוחצים על הטריגר שרוצים להגדיר.

  4. בקטע המתקדם, בקטע משתני החלפה, לוחצים על + הוספת משתנה.

  5. מזינים את השם והערך של המשתנה. קידומת הערך היא body.

    לדוגמה, כדי להחליף את _REPO_URL בשדה נתוני מטען ייעודי repository.clone_url ואת _COMMIT_SHA ב-SHA של הקומיט האחרון ב-YAML של Cloud Build, מזינים את השמות והערכים הבאים:

    • משתנה 1: _REPO_URL ערך 1: $(body.repository.clone_url)
    • משתנה 2: _COMMIT_SHA ערך 2: $(body.after)

    קובץ ה-YAML של Cloud Build נראה כך:

    steps:
- name: gcr.io/cloud-builders/git
  env:
  - '_REPO_URL=$_REPO_URL'
  - '_COMMIT_SHA=$_COMMIT_SHA'
  script: |
    #!/bin/sh
    git clone ${_REPO_URL} /workspace
    cd /workspace
    git reset --hard ${_COMMIT_SHA}

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