חיבור למאגר ב-GitHub

דור ראשון דור שני

בדף הזה מוסבר איך לחבר מאגר GitHub ל-Cloud Build. מידע נוסף על מאגרי Cloud Build

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

• מפעילים את Cloud Build API ואת Secret Manager API.

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

  כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

  הפעלת ממשקי ה-API

• הקוד שלכם צריך להיות מוכן במאגר ב-GitHub.
• במאגר המקור שלכם ב-GitHub צריך להיות Dockerfile או קובץ הגדרות של Cloud Build.
• אם אתם מחברים את המאגר ל-Cloud Build בפעם הראשונה, ודאו שיש לכם הרשאות אדמין במאגר. מידע נוסף על הרשאות למאגרים ב-GitHub זמין במאמר רמות הרשאה למאגרים בארגון.

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

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

התחברות למארח ב-GitHub

המסוף

כדי לחבר את המאגר שלכם ב-GitHub ל-Cloud Build:

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

   פתיחת הדף Repositories

   יוצג הדף מאגרי מידע.

2. בבורר הפרויקטים בסרגל העליון, בוחרים את הפרויקט הרצוי. Google Cloud

3. בחלק העליון של הדף, לוחצים על הכרטיסייה דור שני.

4. לוחצים על Create host connection (יצירת חיבור למארח) כדי לחבר מארח חדש ל-Cloud Build.

5. בחלונית הימנית, בוחרים באפשרות GitHub כספק המקור.

6. בקטע Configure Connection (הגדרת החיבור), מזינים את הפרטים הבאים:

   • אזור: בוחרים אזור לקישור.

     הערה: חובה לציין אזור. החיבור שלכם לא יכול להתקיים באופן גלובלי.

   • שם: מזינים שם לחיבור.

7. אופציונלי: אם רוצים לנהל את מפתחות ההצפנה שמשמשים להצפנת אסימוני הגישה למאגרי GitHub, עוברים לקטע הצפנה ובוחרים מפתח של Cloud Key Management Service. מידע נוסף זמין במאמר בנושא הפעלת מפתחות הצפנה בניהול הלקוח ב-Secret Manager.

8. לוחצים על Connect.

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

   ‫Cloud Build מבקש הרשאה מחשבון המשתמש שלכם ב-GitHub ושומר את טוקן ההרשאה שמתקבל כסוד ב-Secret Manager בפרויקט שלכם. אסימון ההרשאה משמש לאימות הגישה של חשבון המשתמש שלכם להתקנה של אפליקציית Cloud Build GitHub ולמאגרים המקושרים. חשבון סוכן השירות של Cloud Build‏ (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) משמש לגישה לסוד. כדי לראות את הסוד, אפשר לעיין במאמר בנושא הצגת רשימת הסודות ופרטי הסודות.

   הערה: אפשר להשתמש באימות הזה כדי ליצור חיבורים נוספים באותו פרויקט. מומלץ להשתמש בחשבון רובוט או בחשבון שמשותף לצוות, במקום בחשבון GitHub אישי, כדי לשמור על אבטחת החיבורים.

   אחרי שמאשרים את אפליקציית Cloud Build GitHub, מועברים לדף Repositories ב-Cloud Build.

gcloud

כדי לחבר את המארח ב-GitHub באמצעות gcloud, מבצעים את השלבים הבאים:

הערה: כדי לבצע את שלבי ההתקנה, צריך לבצע פעולות בדפדפן האינטרנט.

1. מזינים את הפקודה הבאה כדי ליצור חיבור למאגר GitHub:

    gcloud builds connections create github CONNECTION_NAME --region=REGION
   

   כאשר:

   • ‫CONNECTION_NAME הוא השם של החיבור שיופיע ב-Cloud Build.

   • ‫REGION הוא האזור של הטריגר.

     הערה: חובה לציין אזור. החיבור שלכם לא יכול להתקיים באופן גלובלי.

   אחרי שמריצים את הפקודה gcloud builds connections, מופיע קישור לאישור אפליקציית Cloud Build GitHub.

2. מתחברים לחשבון github.com.

   הערה: אפשר להשתמש באימות הזה כדי ליצור חיבורים נוספים באותו פרויקט. מומלץ להשתמש בחשבון רובוט או בחשבון שמשותף לצוות, במקום בחשבון GitHub אישי, כדי לשמור על אבטחת החיבורים.

3. לוחצים על הקישור כדי לאשר את אפליקציית Cloud Build GitHub.

   אחרי שמאשרים את האפליקציה, Cloud Build שומר אסימון אימות כסוד ב-Secret Manager בפרויקט Google Cloud. אפשר לראות את הסודות בדף Secret Manager.

4. מתקינים את אפליקציית Cloud Build GitHub בחשבון או בארגון שבבעלותכם.

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

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

    gcloud builds connections describe CONNECTION_NAME --region=REGION
   

   כאשר:

   • ‫CONNECTION_NAME הוא השם של חיבור המארח שלכם ב-GitHub ב-Cloud Build.
   • ‫REGION הוא האזור של הטריגר.

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

חיבור לתוכנית אירוח ב-GitHub באופן פרוגרמטי

Terraform

כדי לחבר את המארח שלכם ב-GitHub ל-Cloud Build באמצעות פלאגין שמתממשק עם שירותים חיצוניים של Google Terraform, צריך לבצע את השלבים הבאים:

1. מתקינים את אפליקציית Cloud Build GitHub בחשבון GitHub או בארגון שבבעלותכם.

2. יצירת אסימון גישה אישי.

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

   • repo כדי להעניק גישה מלאה למאגרים ציבוריים ופרטיים.
   • read:user כדי להעניק גישה לקריאת נתוני הפרופיל של המשתמש.
   • ‫read:org לגישת קריאה בלבד לחברות בארגון ולפרויקטים (אם האפליקציה מותקנת בארגון).

   אחרי שיוצרים את אסימון הגישה האישי, שומרים אותו במקום מאובטח. תשתמשו באסימון שנוצר בשלבים הבאים.

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

בדוגמה הבאה, קטע הקוד מבצע את הפעולות הבאות:

• הגדרת ספק Google של Terraform

• יצירת סוד לאחסון אסימוני גישה אישיים ל-GitHub כדי להעניק הרשאות לסוכן השירות של Cloud Build לגשת לסוד

• יצירת חיבור ל-GitHub

  // Configure the terraform google provider
  terraform {
    required_providers {
      google = {}
     }
  }
  
  // Create a secret containing the personal access token and grant permissions to the Service Agent
  resource "google_secret_manager_secret" "github_token_secret" {
      project = PROJECT_ID
      secret_id = SECRET_ID
  
      replication {
          auto {}
      }
  }
  
  resource "google_secret_manager_secret_version" "github_token_secret_version" {
      secret = google_secret_manager_secret.github_token_secret.id
      secret_data = GITHUB_PAT
  }
  
  data "google_iam_policy" "serviceagent_secretAccessor" {
      binding {
          role = "roles/secretmanager.secretAccessor"
          members = ["serviceAccount:[e-mail]"]
      }
  }
  
  resource "google_secret_manager_secret_iam_policy" "policy" {
    project = google_secret_manager_secret.github_token_secret.project
    secret_id = google_secret_manager_secret.github_token_secret.secret_id
    policy_data = data.google_iam_policy.serviceagent_secretAccessor.policy_data
  }
  
  // Create the GitHub connection
  resource "google_cloudbuildv2_connection" "my_connection" {
      project = PROJECT_ID
      location = REGION
      name = CONNECTION_NAME
  
      github_config {
          app_installation_id = INSTALLATION_ID
          authorizer_credential {
              oauth_token_secret_version = google_secret_manager_secret_version.github_token_secret_version.id
          }
      }
      depends_on = [google_secret_manager_secret_iam_policy.policy]
  }
  

כאשר:

• ‫PROJECT_NUMBER הוא מספר הפרויקט שלכם ב- Google Cloud .
• ‫SECRET_ID הוא המזהה של האסימון או הסוד ב-Secret Manager.
• ‫GITHUB_PAT הוא אסימון הגישה של אסימון הגישה האישי ב-GitHub.
• ‫PROJECT_ID הוא מזהה הפרויקט. Google Cloud
• ‫REGION הוא האזור של החיבור שלך.
• ‫CONNECTION_NAME הוא השם של החיבור שיופיע ב-Cloud Build.
• ‫INSTALLATION_ID הוא מזהה ההתקנה של אפליקציית Cloud Build GitHub. אפשר למצוא את מזהה ההתקנה בכתובת ה-URL של אפליקציית Cloud Build GitHub. בכתובת ה-URL הבאה, https://github.com/settings/installations/1234567, מזהה ההתקנה הוא הערך המספרי 1234567.

gcloud

כדי לחבר את המארח ב-GitHub באמצעות אסימון קיים ומזהה התקנה שהתקבלו מחיבור קודם, צריך לבצע את השלבים הבאים:

הערה: כשמשתמשים באסימון ובמזהה התקנה קיימים כדי ליצור חיבור, למשל מסקריפט, לא נדרשת התערבות ידנית באמצעות דפדפן אינטרנט.

1. מתקינים את אפליקציית Cloud Build GitHub בחשבון GitHub או בארגון שבבעלותכם.

2. יצירת אסימון גישה אישי.

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

   • repo כדי להעניק גישה מלאה למאגרים ציבוריים ופרטיים.
   • read:user כדי להעניק גישה לקריאת נתוני הפרופיל של המשתמש.
   • ‫read:org לגישת קריאה בלבד לחברות בארגון ולפרויקטים (אם האפליקציה מותקנת בארגון).

   אחרי שיוצרים את אסימון הגישה האישי, שומרים אותו במקום מאובטח. תשתמשו באסימון שנוצר בשלבים הבאים.

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

3. כדי לאחסן את האסימון ב-Secret Manager בפרויקט Google Cloud , מריצים את הפקודה הבאה:

       echo -n TOKEN | gcloud secrets create SECRET_NAME --data-file=-
   

   כאשר:

   • ‫TOKEN הוא אסימון הגישה האישי שלכם.
   • ‫SECRET_NAME הוא השם שרוצים לתת לסוד ב-Secret Manager.

4. נותנים לסוכן השירות של Cloud Build גישה לסוד, כאשר SECRET_NAME הוא שם הסוד ששמור ב-Secret Manager:

     PROJECT_ID=$(gcloud config list --format="value(core.project)")
     PN=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")
     CLOUD_BUILD_SERVICE_AGENT="service-${PN}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
     gcloud secrets add-iam-policy-binding SECRET_NAME \
       --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT}" \
       --role="roles/secretmanager.secretAccessor"
   

5. יוצרים את החיבור ל-GitHub:

     gcloud builds connections create github CONNECTION_NAME \
       --authorizer-token-secret-version=projects/PROJECT_ID/secrets/SECRET_NAME/versions/1  \
       --app-installation-id=INSTALLATION_ID --region=REGION
   

   כאשר:

   • ‫CONNECTION_NAME הוא שם של חיבור מארח GitHub ב-Cloud Build.
   • ‫PROJECT_ID הוא מזהה הפרויקט. Google Cloud
   • ‫SECRET_NAME הוא השם של הסוד שמאוחסן ב-Secret Manager.
   • ‫INSTALLATION_ID הוא מזהה ההתקנה של אפליקציית GitHub. אפשר למצוא את מזהה ההתקנה בכתובת ה-URL של אפליקציית Cloud Build GitHub. בכתובת ה-URL הבאה, https://github.com/settings/installations/1234567, מזהה ההתקנה הוא הערך המספרי 1234567.
   • ‫REGION הוא האזור של החיבור שלך.

חיבור מאגר ב-GitHub

המסוף

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

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

   פתיחת הדף Repositories

   יוצג הדף מאגרי מידע.

2. בחלק העליון של הדף, לוחצים על הכרטיסייה דור שני.

3. לוחצים על Link Repositories (קישור מאגרים) כדי לקשר מאגרים מהחיבור.

   מוצגת החלונית Connect Repositories (קישור מאגרי קוד).

4. בחלונית Connect Repositories (קישור מאגרי קוד), מזינים את הפרטים הבאים:

   1. Connection (חיבור): בוחרים חיבור מהתפריט הנפתח.

   2. מאגר: בוחרים מאגר לקשר לחיבור.

   3. שם המאגר: מזינים שם למאגר.

      1. נוצר: בוחרים באפשרות הזו כדי שמערכת Cloud Build תיצור באופן אוטומטי שמות של מאגרים בשבילכם עבור מאגרים נבחרים.

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

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

5. לוחצים על Link (קישור) כדי לקשר את המאגר לחיבור.

gcloud

כדי להוסיף מאגר GitHub לחיבור, מזינים את הפקודה הבאה:

   gcloud builds repositories create REPO_NAME \
     --remote-uri=REPO_URI \
     --connection=CONNECTION_NAME --region=REGION

כאשר:

• ‫REPO_NAME הוא שם המאגר.
• ‫REPO_URI הוא הקישור למאגר שלכם ב-GitHub. לדוגמה, https://github.com/cloud-build/test-repo.git.
• ‫CONNECTION_NAME הוא השם שניתן לחיבור המארח של GitHub Enterprise שנוצר ב-Cloud Build מתוך Connect to a GitHub host.
• ‫REGION הוא האזור של החיבור שלך.

Terraform

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

    resource "google_cloudbuildv2_repository" "my_repository" {
      project = "PROJECT_ID"
      location = "REGION"
      name = "REPO_NAME"
      parent_connection = google_cloudbuildv2_connection.my_connection.name
      remote_uri = "URI"
  }

כאשר:

• ‫PROJECT_ID הוא מזהה הפרויקט. Google Cloud
• ‫REPO_NAME הוא השם של המאגר ב-GitHub.
• ‫REGION הוא האזור של החיבור שלך.
• ‫URI הוא מארח ה-URI של המאגר. לדוגמה, https://github.com/myuser/myrepo.git.

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

• כאן מוסבר איך יוצרים מאגרים מ-GitHub.
• איך מבצעים פריסות כחולות-ירוקות ב-Compute Engine
• איך מציינים מאגרי מידע נוספים כתלות ב-build.