חיבור ל-Jenkins

אפשר להתחיל גרסאות build אוטומטיות באמצעות טריגרים של Jenkins ו-webhooks של Secure Source Manager.

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

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

• אדמין של מאגר Secure Source Manager (roles/securesourcemanager.repoAdmin) במאגר
• ‫Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) במופע Secure Source Manager

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

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

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

הגדרת טריגר webhook

‫Jenkins משתמש בפלאגינים של טריגרים לפיתוח גרסת Build כדי להפעיל אוטומציה של CI/CD. אפשר להגדיר טריגרים שיאזינו לאירועים נכנסים, למשל כששולחים קומיט חדש למאגר או כשמתחילים בקשת משיכה, ואז יבצעו אוטומטית בנייה כשאירועים חדשים יגיעו. אפשר גם להגדיר טריגרים כדי ליצור קוד בכל שינוי במאגר קוד המקור, או רק בשינויים שתואמים לקריטריונים מסוימים.

כדי להגדיר טריגר כללי של Jenkins webhook:

1. מתקינים את Git Plugin,‏ SSH Credential Plugin ו-Generic Webhook Trigger Plugin בשרת Jenkins.

2. יוצרים זוג מפתחות SSH תקין בשרת Jenkins. מנהל המקורות המאובטח תומך רק במפתחות מסוג RSA.

3. כדי להוסיף את הדומיין של מופע Secure Source Manager לקובץ known_hosts של שרת Jenkins SSH, מריצים את הפקודה הבאה:

   ssh -t git@INSTANCE_ID-INSTANCE_PROJECT_NUMBER-ssh.us-central1.sourcemanager.dev
   

   כאשר:

   • ‫INSTANCE_ID הוא השם של מופע Secure Source Manager.
   • ‫INSTANCE_PROJECT_NUMBER הוא מספר הפרויקט של מופע Secure Source Manager. במאמר זיהוי פרויקטים מוסבר איפה אפשר למצוא את מספר הפרויקט.

   לדוגמה, הפקודה הבאה מוסיפה את דומיין המופע של מופע בשם prod-test-instance עם מספר פרויקט 123456789.

   ssh -t git@prod-test-instance-123456789-ssh.us-central1.sourcemanager.dev
   

   משיבים yes כדי להוסיף את דומיין המופע לרשימת המארחים המוכרים.

4. בדף Manage Credentials ב-Jenkins:

   1. בוחרים באפשרות שם משתמש SSH עם מפתח פרטי.
   2. מדביקים את המפתח הפרטי של SSH של שרת Jenkins.
   3. בתפריט הנפתח סוג, ממלאים את שאר השדות לפי הצורך.

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

6. בממשק האינטרנט של Jenkins, יוצרים משימת Jenkins חדשה.

7. בדף ההגדרות של משימת Jenkins, בקטע Source Code Management, בוחרים באפשרות Git.

8. בקטע Git, מדביקים את כתובת ה-URL של מאגר ה-SSH של Secure Source Manager ככתובת ה-URL של המאגר, מזינים את ענפי הבנייה (למשל */main) ובוחרים את פרטי הכניסה של מפתח ה-SSH הפרטי השמורים שהוספתם קודם בדף Manage Credentials.

9. בקטע Build Triggers (יצירת טריגרים), בוחרים באפשרות Generic Webhook Trigger (טריגר כללי של Webhook).

   אפשר להוסיף אסימון כדי שהג'וב יופעל רק אם האסימון הזה יסופק בזמן ההפעלה. כדי להוסיף טוקן, בקטע Generic Webhook Trigger (טריגר כללי של Webhook), אפשר להזין טוקן בשדה Token (טוקן).

10. בקטע Build (בנייה), מציינים סקריפט בנייה שרוצים להשתמש בו למשימת Jenkins הזו. לדוגמה, אפשר להריץ את הפקודה cat README.md כדי להדפיס את התוכן של README.md.

11. לוחצים על שמירה כדי ליצור את משימת Jenkins.

הגדרה של חשבון שירות והענקת ההרשאות הנדרשות

1. אם עדיין אין לכם חשבון שירות שבו אתם רוצים להשתמש, צרו חשבון שירות.

   חשוב לוודא שיש לכם הרשאה מסוג iam.serviceAccounts.actAs בחשבון השירות. ההרשאה הזו היא חלק מהתפקיד 'משתמש בחשבון שירות' (roles/iam.serviceAccountUser).

2. בממשק האינטרנט של Secure Source Manager, לוחצים על התפריט more_vert אפשרויות נוספות.

3. לוחצים על מפתחות SSH של חשבון שירות. נפתח הדף Service account SSH keys ומוצגת רשימה של כל המפתחות הקיימים שהוספתם.

4. לוחצים על הוספת מפתח.

5. בדף Add SSH key (הוספת מפתח SSH), מזינים את הערכים הבאים של המפתח:

   1. חשבון שירות: כתובת האימייל בחשבון השירות שרוצים להשתמש בו עם מפתח ה-SSH בפורמט SA_NAME@PROJECT_ID.iam.gserviceaccount.com

      כאשר:

      • ‫SA_NAME הוא השם של חשבון השירות.
      • ‫PROJECT_ID הוא מזהה הפרויקט שבו נוצר חשבון השירות.

   2. מפתח ציבורי SSH: מפתח ה-SSH הציבורי של Jenkins.

מתן הרשאות לסוכן השירות של Secure Source Manager

אם חשבון השירות לא נמצא באותו פרויקט כמו המופע של Secure Source Manager, צריך גם להקצות לסוכן השירות של Secure Source Manager את התפקיד 'יצירת אסימונים בחשבון שירות' (roles/iam.serviceAccountTokenCreator) או את ההרשאה iam.serviceAccounts.signJwt.

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

1. מריצים את הפקודה הבאה כדי לקבל את מדיניות ה-IAM הקיימת של חשבון השירות:

   gcloud iam service-accounts get-iam-policy SERVICE_ACCOUNT \
       --format json
   

   כאשר SERVICE_ACCOUNT הוא חשבון השירות שבו רוצים להשתמש. הפורמט של החשבון צריך להיות מזהה מספרי של חשבון שירות או כתובת אימייל, כמו 123456789876543212345 או my-iam-account@somedomain.com.

   הפלט כולל את כל הקישורים הקיימים, או, אם אין קישורים, את הערך etag שדומה לזה:

   {
   "etag": "BwUjHYKJUiQ="
   }
   

2. מעתיקים את הפלט לקובץ חדש בשם policy.json.

3. כדי להעניק לסוכן השירות של Secure Source Manager את התפקיד 'יצירת אסימונים בחשבון שירות' (roles/iam.ServiceAccountTokenCreator), משנים את policy.json ומוסיפים את השורה הבאה:

   {
       "role": "roles/iam.serviceAccountTokenCreator",
       "members": [
           "serviceAccount:service-INSTANCE_PROJECT_NUMBER@gcp-sa-sourcemanager.iam.gserviceaccount.com"
       ]
   }
   

   כאשר INSTANCE_PROJECT_NUMBER הוא מספר הפרויקט של המכונה של Secure Source Manager.

4. מריצים את הפקודה הבאה כדי להחליף את מדיניות ה-IAM הקיימת של חשבון השירות:

   gcloud iam service-accounts set-iam-policy SERVICE_ACCOUNT POLICY_FILE
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫SERVICE_ACCOUNT במזהה או בכתובת האימייל של חשבון השירות.
   • ‫POLICY_FILE במיקום ובשם של קובץ בפורמט JSON, כולל המדיניות החדשה.

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

1. בממשק האינטרנט של Secure Source Manager, עוברים למאגר שרוצים להעניק בו הרשאות לחשבון השירות.
2. לוחצים על הכרטיסייה Permissions.
3. לוחצים על הוספת משתמשים.
4. בשדה Add principal, מזינים את כתובת האימייל של חשבון השירות.
5. בתפריט הנפתח Role (תפקיד), בוחרים באפשרות Secure Source Manager Repository Reader (קריאת מאגר Secure Source Manager).

6. מריצים את הפקודה הבאה כדי להקצות לחשבון השירות את התפקיד securesourcemanager.instanceAccessor:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:SA_EMAIL \
       --role=roles/securesourcemanager.instanceAccessor
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫PROJECT_ID במזהה הפרויקט של מופע Secure Source Manager.
   • ‫SA_EMAIL מחליפים בכתובת האימייל בחשבון השירות.

הגדרת webhook

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

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

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

6. אם השתמשתם באסימון האופציונלי כשקבעתם את ההגדרות של הטריגר של Jenkins, כתובת ה-URL של הטריגר של Jenkins תכיל את האסימון הזה בסוף. כדי למנוע חשיפה של האסימון, מסירים אותו מסוף כתובת היעד ומעתיקים אותו לשדה Sensitive Query String (מחרוזת שאילתה רגישה).

   כדי למצוא את האסימון בכתובת ה-URL של הטריגר, מחפשים את הטקסט שמתחיל ב- token=

   לדוגמה, אם כתובת ה-URL שלכם דומה לכתובת הבאה: https://jenkins-server.com/generic-webhook-trigger/invoke?token=jenkins-job1

   מעתיקים את החלק שמתחיל בסימן השאלה ?token=jenkins-job1 ומסירים אותו מהשדה כתובת יעד. אחר כך מסירים את סימן השאלה הראשוני, מעבירים את החלק שנותר token=jenkins-job1 לשדה מחרוזת שאילתה רגישה.

7. בקטע הפעלה ב, בוחרים באחת מהאפשרויות הבאות:

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

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

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

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

10. התגובה לפעולה מאתר אחר (webhook) מוצגת בדף Webhooks.

בדיקת ה-webhook

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

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

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

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

4. בפרויקט Jenkins, צופים ב-build שהופעל על ידי אירוע הבדיקה בBuild History.

5. אחרי ששולחים את משלוח הבדיקה הראשון, אפשר גם לראות את הבקשה ואת התגובה למשלוח הבדיקה בקטע Recent deliveries (משלוחים אחרונים) בדף של Secure Source Manager webhook.

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

• מאמרי העזרה של Jenkins