Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

חיבור למארח GitHub Enterprise

בדף הזה מוסבר איך לחבר מארח של GitHub Enterprise ל-Cloud Build.

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

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

מוודאים שמותקנת הגרסה העדכנית של GitHub Enterprise.
חשוב לוודא שמיפיתם דומיין בהתאמה אישית למארח שלכם ב-GitHub Enterprise, ושיש לכם אישור SSL תקף למארח.

הערה: אם המארח של GitHub Enterprise פועל במכונה ב-Compute Engine, אתם יכולים ליצור מאזן עומסים חיצוני מסוג HTTP(S) ולהשתמש באישור SSL שמנוהל על ידי Google עבור המכונה.
אם מופע GitHub Enterprise שלכם מתארח ברשת פרטית, כדאי לעיין במאמר יצירת מאגרים מ-GitHub Enterprise ברשת פרטית לפני שמבצעים את ההוראות שבדף הזה.

הרשאות IAM נדרשות

כדי לחבר את המארח שלכם ב-GitHub Enterprise, צריך להקצות לחשבון המשתמש שלכם את התפקיד 'אדמין של חיבור Cloud Build' (roles/cloudbuild.connectionAdmin).

במאמר הגדרת גישה למשאבי Cloud Build מוסבר איך מוסיפים את התפקידים הנדרשים לחשבון המשתמש. במאמר תפקידים והרשאות ב-IAM מוסבר בהרחבה על תפקידי IAM שמשויכים ל-Cloud Build.

כדי ליצור חיבורים באמצעות שלבי ההתקנה של gcloud, צריך להקצות את התפקיד Secret Manager Admin ‏ (roles/secretmanager.admin) לסוכן השירות של Cloud Build. לשם כך, מריצים את הפקודה הבאה בפרויקט Google Cloud :

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

אם מופע GitHub Enterprise שלכם מתארח ברשת פרטית, כדאי לעיין במאמר Build repositories from GitHub Enterprise in a private network כדי לקבל מידע על תפקידי IAM נוספים שנדרשים לפני חיבור המארח.

חיבור למארח GitHub Enterprise

המסוף

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

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

פתיחת הדף Repositories

יוצג הדף מאגרי מידע.
בבורר הפרויקטים בסרגל העליון, בוחרים את הפרויקט הרצוי. Google Cloud
בחלק העליון של הדף, לוחצים על הכרטיסייה דור שני.
לוחצים על Create host connection (יצירת חיבור למארח) כדי לחבר מארח חדש ל-Cloud Build.
בחלונית הימנית, בוחרים באפשרות GitHub Enterprise כספק המקור.
בקטע Configure Connection (הגדרת החיבור), מזינים את הפרטים הבאים:
- אזור: בוחרים אזור לקישור.
  
  הערה: חובה לציין אזור. החיבור שלכם לא יכול להתקיים באופן גלובלי.
- שם: מזינים שם לחיבור.
בקטע פרטי המארח, עוברים אל כתובת ה-URL של המארח ומזינים את כתובת ה-URL של המארח לחיבור. לדוגמה, github.example.com.
אופציונלי: אם רוצים לנהל את מפתחות ההצפנה שמשמשים להצפנת אסימוני הגישה למאגרי GitHub Enterprise, עוברים לקטע הצפנה ובוחרים מפתח של Cloud Key Management Service. מידע נוסף זמין במאמר בנושא הפעלת מפתחות הצפנה בניהול הלקוח ב-Secret Manager.
בקטע Networking, מתחת לConnection type, בוחרים באחת מהאפשרויות הבאות:
- אינטרנט ציבורי: בוחרים באפשרות הזו אם אפשר לגשת למופע באמצעות האינטרנט הציבורי.
- רשת פרטית: בוחרים באפשרות הזו אם המופע מתארח ברשת פרטית. לאחר מכן, מגדירים את האפשרויות הבאות:
  1. אישור CA: לוחצים על 'עיון' כדי להעלות את האישור בחתימה עצמית.
    
    הערה: גודל האישור לא יכול לחרוג מ-10KB והוא צריך להיות בפורמט PEM‏ (.pem,‏ .cer או .crt). אם לא ממלאים את הקטע הזה, נעשה שימוש בקבוצת אישורים שמוגדרת כברירת מחדל.
  2. בקטע Service Directory service, בוחרים את המיקום של השירות:
    - בפרויקט CURRENT_PROJECT
    - בפרויקט אחר
    - הזנה ידנית
  3. הזן את פריטי המידע הבאים:
    - פרויקט: אם בחרתם באפשרות בפרויקט אחר או באפשרות הזנה ידנית, מזינים או בוחרים את מזהה הפרויקט שלכם מתוך התפריט הנפתח. Google Cloud
    - אזור: בשדה הזה האזור של החיבור שלכם נבחר מראש. האזור שצוין לשירות חייב להיות זהה לאזור שמשויך לחיבור.
    - מרחב שמות: בוחרים את מרחב השמות של השירות.
    - שירות: בוחרים את שם השירות במרחב השמות.
לוחצים על Connect.

אחרי שתלחצו על הלחצן Connect, תתבקשו ליצור אפליקציית GitHub במארח GitHub Enterprise ולהתקין את האפליקציה בחשבון משתמש או בארגון. נוצר אסימון אימות מהמארח של GitHub Enterprise והוא מאוחסן בפרויקט הזה כסוד ב-Secret Manager. אפשר לבטל את הגישה בכל שלב על ידי הסרת ההתקנה של אפליקציית GitHub מהמארח או מחיקתה.

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

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

gcloud

כדי לחבר את המארח שלכם ב-GitHub Enterprise ל-Cloud Build באמצעות פקודות gcloud:

מזינים את הפקודה הבאה כדי ליצור חיבור ל-GitHub Enterprise:
```
gcloud builds connections create github-enterprise CONNECTION_NAME \
  --host-uri=HOST_URI --region=REGION
```
כאשר:
- ‫CONNECTION_NAME הוא שם לחיבור של מארח GitHub Enterprise ב-Cloud Build.
- ‫HOST_URI הוא ה-URI של מופע GitHub Enterprise. לדוגמה, https://mmy-ghe-server.net.
- ‫REGION הוא האזור של החיבור שלך.
אם מופע GitHub Enterprise שלכם נמצא ברשת פרטית, צריך לציין את משאב Service Directory. אפשר גם לציין את אישור ה-CA.
```
--service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
--ssl-ca-file=SSL_CA_FILEPATH
```
כאשר:
- ‫PROJECT_ID הוא מזהה הפרויקט. Google Cloud
- ‫REGION הוא האזור של החיבור שלך.
- ‫NAMESPACE הוא מרחב השמות של השירות.
- ‫SERVICE_NAME הוא השם של השירות במרחב השמות.
- ‫SSL_CA_FILEPATH הוא הנתיב לאישור ה-CA.
אחרי שמריצים את הפקודה gcloud builds connections..., מקבלים קישור להתקנת אפליקציית Cloud Build GitHub.
עוברים לקישור שמופיע בשלב הקודם כדי ליצור ולהתקין את אפליקציית Cloud Build GitHub בשרת הארגוני.
מזינים את הפקודה הבאה כדי לאמת את החיבור:
```
gcloud builds connections describe CONNECTION_NAME --region=REGION
```
כאשר:
- ‫CONNECTION_NAME הוא שם החיבור של מארח GitHub Enterprise ב-Cloud Build.
- ‫REGION הוא האזור של החיבור שלך.
אם השדה installationState מוגדר לערך COMPLETE, סימן שהתקנתם את החיבור בהצלחה. אחרת, בשדה installationState מופיע קישור לשלבים נוספים שנדרשים.

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

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

רושמים אפליקציית GitHub חדשה. לדוגמה, אפשר לרשום אפליקציית GitHub חדשה בכתובת https://my-ghe-server.net/settings/apps/new.
ממלאים את השדות בדף:
1. GitHub App Name (שם אפליקציית GitHub): מזינים שם לאפליקציה.
2. כתובת ה-URL של דף הבית: מזינים כתובת URL ל-GitHub Enterprise Server.
3. מבטלים את הסימון בתיבה Expire user authorization tokens (הטוקנים של הרשאות המשתמש יפוגו).
4. בקטע Webhook, מבצעים את הפעולות הבאות:
  - פעיל: מסמנים את התיבה כדי להפעיל את ה-webhook.
  - Webhook URL: מזינים את כתובת ה-URL של ה-webhook. לדוגמה, https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook. האזור בכתובת ה-URL של ה-webhook צריך להיות זהה לאזור של החיבור.
  - Webhook secret (סוד של webhook): מזינים מחרוזת שנוצרה באופן אקראי ורושמים אותה.
5. בקטע Permissions, מציינים את ההרשאות הבאות:
  - הרשאות למאגר:
    - Checks: קריאה וכתיבה
    - Contents: קריאה וכתיבה
    - Issues: קריאה בלבד
    - מטא-נתונים קריאה בלבד
    - סטטוסים של קומיטים: קריאה בלבד
    - Pull requests: קריאה בלבד
6. בקטע Subscribe to events (הרשמה לאירועים), מסמנים את התיבות הבאות:
  - הפעלת בדיקה
  - Check suite
  - תגובת קומיט
  - הוספת תגובה לבעיה
  - בקשת מיזוג
  - תגובה לבקשת משיכה
  - Push
  - מאגר
7. מסמנים את התיבה Any account כדי לאפשר לכל משתמש או ארגון להתקין את אפליקציית GitHub.
לוחצים על Create GitHub app (יצירת אפליקציית GitHub) כדי ליצור את אפליקציית GitHub.

אחרי שלוחצים על Create GitHub app (יצירת אפליקציית GitHub), מועברים לדף האפליקציה. רושמים את מזהה האפליקציה ואת שם האפליקציה. הסלאג של האפליקציה מופיע בפלח האחרון של כתובת ה-URL של הדף. לדוגמה, https://my-ghe-server.net/settings/apps/{app-slug}.
בקטע מפתחות פרטיים, לוחצים על יצירת מפתח פרטי.

מאחסנים את הקובץ שהורדתם במקום מאובטח.
בחלונית הימנית, בוחרים באפשרות התקנת אפליקציה.

בוחרים את המשתמש או הארגון שרוצים להתקין את האפליקציה. אחרי שהאפליקציה מותקנת, רושמים את מזהה ההתקנה. מזהה ההתקנה מופיע בפלח האחרון של כתובת ה-URL של הדף. לדוגמה, https://my-ghe-server.net/settings/installations/{installation-id}.

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

Terraform

אחרי שמתקינים את אפליקציית GitHub, אפשר לחבר את המארח של GitHub Enterprise ל-Cloud Build באמצעות ספק Google Terraform.

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

הגדרת ספק Google של Terraform
יצירת סוד לשמירת המפתח הפרטי של אפליקציית GitHub והסוד של ה-webhook
מתן ההרשאות הנדרשות לסוכן השירות של Cloud Build כדי לגשת לסודות

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

// Configure the terraform google provider
terraform {
  required_providers {
    google = {}
  }
}

// create Secrets and grant permissions to the Service Agent
resource "google_secret_manager_secret" "private-key-secret" {
    project = "PROJECT_ID"
    secret_id = "PRIVATE_KEY_SECRET"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "private-key-secret-version" {
    secret = google_secret_manager_secret.private-key-secret.id
    secret_data = file("private-key.pem")
}

resource "google_secret_manager_secret" "webhook-secret-secret" {
    project = "PROJECT_ID"
    secret_id = "WEBHOOK_SECRET"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "webhook-secret-secret-version" {
    secret = google_secret_manager_secret.webhook-secret-secret.id
    secret_data = "WEBHOOK_SECRET_VALUE"
}

data "google_iam_policy" "serviceagent-secretAccessor" {
    binding {
        role = "roles/secretmanager.secretAccessor"
        members = ["serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"]
    }
}

resource "google_secret_manager_secret_iam_policy" "policy-pk" {
  project = google_secret_manager_secret.private-key-secret.project
  secret_id = google_secret_manager_secret.private-key-secret.secret_id
  policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-whs" {
  project = google_secret_manager_secret.webhook-secret-secret.project
  secret_id = google_secret_manager_secret.webhook-secret-secret.secret_id
  policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
}

// create the connection and add the repository resource ---
resource "google_cloudbuildv2_connection" "my-connection" {
    project = "PROJECT_ID"
    location = "REGION"
    name = "CONNECTION_NAME"

    github_enterprise_config {
        host_uri = "URI"
        private_key_secret_version = google_secret_manager_secret_version.private-key-secret-version.id
        webhook_secret_secret_version = google_secret_manager_secret_version.webhook-secret-secret-version.id
        app_id = "APP_ID"
        app_slug = "APP_SLUG"
        app_installation_id = INSTALLATION_ID
    }

    depends_on = [
        google_secret_manager_secret_iam_policy.policy-pk,
        google_secret_manager_secret_iam_policy.policy-whs
    ]
}

כאשר:

‫PROJECT_ID הוא מזהה הפרויקט. Google Cloud
‫PRIVATE_KEY_SECRET הוא הסוד שמכיל את המפתח הפרטי של אפליקציית GitHub.
‫WEBHOOK_SECRET הוא שם הסוד שמכיל את ערך הסוד של ה-webhook של אפליקציית GitHub.
‫WEBHOOK_SECRET_VALUE הוא הערך של סוד ה-webhook של אפליקציית GitHub.
‫REGION הוא האזור של החיבור שלך.
‫CONNECTION_NAME הוא שם לחיבור של מארח GitHub Enterprise ב-Cloud Build.
‫URI הוא ה-URI של החיבור. לדוגמה, https://my-github-enterprise-server.net.
‫APP_ID הוא המזהה של אפליקציית GitHub.
‫APP_SLUG הוא ה-slug של האפליקציה. לדוגמה, https://github.com/settings/apps/{app-slug}.
‫INSTALLATION_ID הוא מזהה ההתקנה של אפליקציית GitHub. אפשר למצוא את מזהה ההתקנה בכתובת ה-URL של אפליקציית Cloud Build GitHub, ‏ https://github.com/settings/installations/{installation-id}.

gcloud

אחרי שמתקינים את אפליקציית GitHub, מבצעים את השלבים הבאים כדי לקשר את מארח GitHub Enterprise באופן פרוגרמטי באמצעות gcloud:

אחסון הסודות ב-Secret Manager:

echo -n WEBHOOK_SECRET | gcloud secrets create mygheapp-webhook-secret --data-file=-
# creating secret from the downloaded private key:
gcloud secrets create mygheapp-private-key --data-file=PRIVATE_KEY_FILE

כאשר:

‫WEBHOOK_SECRET היא המחרוזת שיצרתם בשביל הסוד של ה-webhook.
‫PRIVATE_KEY_FILE הוא הנתיב למפתח הפרטי שיצרתם.

נותנים לסוכן השירות של Cloud Build גישה לסודות:

PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
CLOUD_BUILD_SERVICE_AGENT="service-$PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"
gcloud secrets add-iam-policy-binding mygheapp-webhook-secret \
  --member="serviceAccount:$CLOUD_BUILD_SERVICE_AGENT" \
  --role="roles/secretmanager.secretAccessor"
gcloud secrets add-iam-policy-binding mygheapp-private-key \
  --member="serviceAccount:$CLOUD_BUILD_SERVICE_AGENT" \
  --role="roles/secretmanager.secretAccessor"

כאשר:

‫PROJECT_ID הוא מזהה הפרויקט. Google Cloud
‫CLOUD_BUILD_SERVICE_AGENT הוא החשבון שלכם לחיוב לפי מוצר ולפי פרויקט.

יוצרים את החיבור ל-GitHub Enterprise:
```
gcloud builds connections create github-enterprise CONNECTION_NAME \
  --host-uri=HOST_URI \
  --app-id=APP_ID \
  --app-slug=APP_SLUG \
  --private-key-secret-version=projects/PROJECT_ID/secrets/mygheapp-private-key/versions/1 \
  --webhook-secret-secret-version=projects/PROJECT_ID/secrets/mygheapp-webhook-secret/versions/1 \
  --app-installation-id=INSTALLATION_ID \
  --region=REGION
```
כאשר:
- ‫CONNECTION_NAME הוא שם לחיבור של מארח GitHub Enterprise ב-Cloud Build.
- ‫HOST_URI הוא ה-URI של מופע GitHub Enterprise. לדוגמה, https://mmy-ghe-server.net.
- ‫APP_ID הוא המזהה של אפליקציית GitHub.
- ‫APP_SLUG הוא ה-slug של האפליקציה. לדוגמה, https://my-ghe-server.net/settings/apps/app-slug.
- ‫PROJECT_ID הוא מזהה הפרויקט. Google Cloud
- ‫INSTALLATION_ID הוא מזהה ההתקנה של אפליקציית GitHub. לדוגמה, ‫https://my-ghe-server.net/settings/installations/installation-id
- ‫REGION הוא האזור של החיבור שלך.
אם מופע GitHub Enterprise שלכם נמצא ברשת פרטית, צריך לציין את משאב Service Directory. אפשר גם לציין את אישור ה-CA.
```
  --service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
  --ssl-ca-file=SSL_CA_FILEPATH
```
כאשר:
- ‫PROJECT_ID הוא מזהה הפרויקט. Google Cloud
- ‫REGION הוא האזור של החיבור שלך.
- ‫NAMESPACE הוא מרחב השמות של השירות.
- ‫SERVICE_NAME הוא השם של השירות במרחב השמות.
- ‫SSL_CA_FILEPATH הוא הנתיב לאישור ה-CA.

חיבור למארח GitHub Enterprise קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

הרשאות IAM נדרשות

חיבור למארח GitHub Enterprise

המסוף

gcloud

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

Terraform

gcloud

השלבים הבאים

חיבור למארח GitHub Enterprise