Se connecter à un hôte GitHub Enterprise

Cette page explique comment connecter un hôte GitHub Enterprise à Cloud Build.

Avant de commencer

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

Autorisations IAM requises

Pour connecter votre hôte GitHub Enterprise, attribuez le rôle Administrateur de connexion Cloud Build (roles/cloudbuild.connectionAdmin) à votre compte utilisateur.

Pour ajouter les rôles requis à votre compte utilisateur, consultez Configurer l'accès aux ressources Cloud Build. Pour en savoir plus sur les rôles IAM associés à Cloud Build, consultez la page Rôles et autorisations IAM.

Pour créer des connexions à l'aide des étapes d'installation de gcloud, accordez le le rôle d'administrateur Secret Manager (roles/secretmanager.admin) à l'agent de service Cloud Build en exécutant la commande suivante : dans votre projet 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"

Si votre instance GitHub Enterprise est hébergée sur un réseau privé, consultez Créer des dépôts à partir de GitHub Enterprise dans un réseau privé pour les rôles IAM supplémentaires requis avant de passer connexion hôte.

Se connecter à un hôte GitHub Enterprise

Console

Pour connecter votre hôte GitHub Enterprise à Cloud Build :

  1. Ouvrez la page Dépôts de la console Google Cloud.

    Ouvrir la page "Dépôts"

    La page Dépôts s'affiche.

  2. Dans le sélecteur de projet de la barre supérieure, sélectionnez votre projet Google Cloud.

  3. En haut de la page, sélectionnez l'onglet 2e génération.

  4. Cliquez sur Créer une connexion hôte pour connecter un nouvel hôte à Cloud Build.

  5. Dans le panneau de gauche, sélectionnez GitHub Enterprise comme fournisseur de source.

  6. Dans la section Configure Connection (Configurer la connexion), saisissez les informations suivantes:

    1. Région : sélectionnez une région pour votre connexion.

    2. Name (Nom) : saisissez le nom de votre connexion.

  7. Dans la section Host details (Détails de l'hôte), saisissez les informations suivantes:

    1. Host URL (URL de l'hôte) : saisissez l'URL de l'hôte pour votre connexion. Par exemple, github.example.com.

    2. Certificat CA : cliquez sur "Parcourir" pour importer votre certificat autosigné.

    3. Sous Type de connexion, sélectionnez l'une des options suivantes :

      1. Internet public : sélectionnez cette option si votre instance est accessible via l'Internet public.

      2. Accès au réseau privé : sélectionnez cette option si votre instance est hébergée sur un réseau privé.

      3. Sous Service de répertoire de services, sélectionnez l'emplacement de votre service :

        • Dans le projet your-project
        • Dans un autre projet
        • Saisie manuelle

        1. Si vous sélectionnez Dans un autre projet ou Saisir manuellement, saisissez le les informations suivantes:

          • Project (Projet) : saisissez ou sélectionnez l'ID de votre projet Google Cloud dans le menu déroulant.

          • Région : ce champ présélectionne la région de votre connexion. Région spécifiée doit correspondre à la région associée à votre connexion.

        2. Espace de noms: sélectionnez l'espace de noms de votre service.

        3. Service : sélectionnez le nom du service dans votre espace de noms.

  8. Cliquez sur Se connecter.

    Après avoir cliqué sur le bouton Connecter, vous serez invité à créer une application GitHub sur votre hôte GitHub Enterprise et à l'installer dans un compte utilisateur ou une organisation. Une le jeton d'authentification de votre hôte GitHub Enterprise sera créé et stocké dans ce en tant que secret Secret Manager. Vous pouvez révoquer l'accès en désinstallant ou en supprimant l'application GitHub de votre hôte à tout moment.

    Cloud Build stocke les données d'authentification Application GitHub en tant que secrets dans Secret Manager de votre projet. Ces données incluent votre clé privée et le secret de votre webhook. La clé privée est utilisée comme méthode d'authentification pour accéder à l'API de l'Enterprise Server. Le secret de webhook permet de valider les événements envoyés du serveur à Cloud Build. Le compte de l'agent de service Cloud Build (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) permet d'accéder à votre secret. Pour afficher votre secret, consultez la section Répertorier les secrets et afficher les détails des secrets.

    Après avoir autorisé l'application GitHub Cloud Build, vous êtes redirigé vers la page Dépôts de Cloud Build.

Vous venez de créer une connexion GitHub Enterprise.

gcloud

Pour connecter votre hôte GitHub Enterprise à Cloud Build à l'aide de gcloud, procédez comme suit:

  1. Saisissez la commande suivante pour créer une connexion GitHub Enterprise :

    gcloud builds connections create github-enterprise CONNECTION_NAME \
  --host-uri=HOST_URI --region=REGION

    Où :

    • CONNECTION_NAME est le nom de votre connexion.
    • HOST_URI est l'URI de votre instance GitHub Enterprise. Exemple :https://mmy-ghe-server.net
    • REGION est la région de votre connexion.

    Si votre instance GitHub Enterprise se trouve sur un réseau privé, spécifiez votre ressource de répertoire de services. Vous pouvez également spécifier votre certificat CA.

    --service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
--ssl-ca-file=SSL_CA_FILEPATH

    Où :

    • PROJECT_ID correspond à votre ID de projet Google Cloud.
    • REGION est la région de votre connexion.
    • NAMESPACE est l'espace de noms de votre service.
    • SERVICE_NAME est le nom du service dans votre espace de noms.
    • SSL_CA_FILEPATH est le chemin d'accès au fichier de votre certificat d'autorité de certification.

    Après avoir exécuté la commande gcloud builds connections..., vous allez : recevoir un lien permettant d'installer l'application GitHub Cloud Build.

  2. Cliquez sur le lien renvoyé à l'étape précédente pour créer et installer Application GitHub Cloud Build sur le serveur de votre entreprise

  3. Saisissez la commande suivante pour vérifier votre connexion:

    gcloud builds connections describe CONNECTION_NAME --region=REGION

    Où :

    • CONNECTION_NAME est le nom de votre connexion.
    • REGION est la région de votre connexion.

    Si le champ installationState est défini sur COMPLETE, la connexion a bien été installée. Sinon, le champ installationState fournit un lien vers les étapes supplémentaires requises.

Vous venez de créer une connexion GitHub Enterprise.

Se connecter à un hôte GitHub Enterprise de manière programmatique

Pour connecter votre hôte GitHub Enterprise de manière programmatique à Cloud Build, vous devez installer l'application GitHub en procédant comme suit :

  1. Enregistrez une nouvelle application GitHub. Par exemple, vous pouvez enregistrer un nouveau l'application GitHub à l'adresse https://my-ghe-server.net/settings/apps/new.

  2. Renseignez les champs de la page:

    1. Nom de l'application GitHub : saisissez un nom pour votre application.
    2. URL de la page d'accueil : saisissez une URL pour votre serveur GitHub Enterprise.
    3. Décochez l'option Expire user authorization tokens (Expirer les jetons d'autorisation utilisateur).
    4. Dans la section Webhook, procédez comme suit :
      • Actif: cochez la case pour activer votre webook.
      • URL du webhook : saisissez l'URL de votre webhook. Exemple :https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook La région de l'URL du webhook doit correspondre à la région de votre connexion.
      • Code secret du webhook: saisissez une chaîne générée de manière aléatoire et notez-la.
    5. Dans la section Autorisations, spécifiez les autorisations suivantes:
      • Autorisations du dépôt :
        • Vérifications: lecture et écriture
        • Contenu : Lecture et écriture
        • Problèmes : lecture seule
        • Métadonnées : lecture seule
        • États des commits : lecture seule
        • Demandes d'extraction: lecture seule
    6. Dans la section S'abonner aux événements, cochez les cases suivantes:
      • Vérifier l'exécution
      • Vérifier la suite
      • Commentaire sur le commit
      • Commentaire sur le problème
      • Demande d'extraction
      • Commentaire pour l'examen de la demande d'extraction
      • Push
      • Dépôt
    7. Cochez la case Tout compte pour autoriser n'importe quel utilisateur ou organisation à installer votre application GitHub.

  3. Cliquez sur Créer une application GitHub pour créer votre application GitHub.

    Lorsque vous cliquez sur Créer une application GitHub, vous êtes redirigé vers la page de votre application. Prenez note de votre ID d'application et de son slug. Le slug de l'application se trouve dans le dernier segment de l'URL de la page. Par exemple, https://my-ghe-server.net/settings/apps/{app-slug}.

  4. Dans la section Clés privées, cliquez sur Générer une clé privée.

    Stockez le fichier téléchargé en lieu sûr.

  5. Dans le volet de gauche, sélectionnez Installer l'application.

    Sélectionnez l'utilisateur ou l'organisation dans lesquels vous souhaitez installer l'application. Une fois l'application installée, notez l'ID d'installation. L'ID d'installation se trouve dans le dernier segment de l'URL de la page. Par exemple, https://my-ghe-server.net/settings/installations/{installation-id}.

Après avoir installé votre application GitHub, procédez comme suit pour connecter votre hôte GitHub Enterprise de manière programmatique à l'aide de Terraform ou de gcloud.

Terraform

Une fois votre application GitHub installée, vous pouvez connecter votre hôte GitHub Enterprise à Cloud Build à l'aide du fournisseur Google Terraform.

Dans l'exemple suivant, l'extrait de code effectue les opérations suivantes :

  • Configure le fournisseur Google Terraform
  • Crée un secret pour stocker la clé privée et le secret du webhook de l'application GitHub
  • Accorde à l'agent de service Cloud Build les autorisations nécessaires pour accéder aux secrets

  • Crée une connexion 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
    ]
}

Où :

  • PROJECT_ID correspond à votre ID de projet Google Cloud.
  • PRIVATE_KEY_SECRET est le secret contenant la clé privée de votre application GitHub.
  • WEBHOOK_SECRET est le nom du secret contenant la valeur secrète du webhook de votre application GitHub.
  • WEBHOOK_SECRET_VALUE est la valeur du secret du webhook de votre application GitHub.
  • REGION est la région de votre connexion.
  • CONNECTION_NAME est le nom de votre connexion GitHub.
  • URI est l'URI de votre connexion. Exemple :https://my-github-enterprise-server.net
  • APP_ID est l'ID de votre application GitHub.
  • APP_SLUG correspond au slug de l'application. Exemple :https://github.com/settings/apps/{app-slug}
  • INSTALLATION_ID correspond à l'ID d'installation de votre application GitHub. Vous le trouverez dans l'URL de votre application GitHub Cloud Build, https://github.com/settings/installations/{installation-id}.

Vous venez de créer une connexion GitHub Enterprise.

gcloud

Après avoir installé votre application GitHub, procédez comme suit pour connecter votre hôte GitHub Enterprise de manière programmatique à l'aide de gcloud :

  1. Stockez vos secrets dans 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

    Où :

    • WEBHOOK_SECRET est la chaîne que vous avez créée pour le secret de votre webhook.
    • PRIVATE_KEY_FILE correspond au chemin d'accès au fichier de la clé privée que vous avez générée.

  2. Accordez à l'agent de service Cloud Build l'accès à vos secrets :

    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"

    Où :

    • PROJECT_ID correspond à votre ID de projet Google Cloud.
    • CLOUD_BUILD_SERVICE_AGENT est votre compte par produit et par projet.

  3. Créez votre connexion 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

    Où :

    • CONNECTION_NAME est le nom de votre connexion.
    • HOST_URI est l'URI de votre instance GitHub Enterprise. Exemple :https://mmy-ghe-server.net
    • APP_ID est l'ID de votre application GitHub.
    • APP_SLUG est le slug de l'application. Exemple :https://my-ghe-server.net/settings/apps/app-slug
    • PROJECT_ID correspond à votre ID de projet Google Cloud.
    • INSTALLATION_ID est l'ID d'installation de votre application GitHub. Par exemple : https://my-ghe-server.net/settings/installations/installation-id
    • REGION est la région de votre connexion.

    Si votre instance GitHub Enterprise se trouve sur un réseau privé, spécifiez votre ressource de répertoire de services. Vous pouvez également spécifier votre certificat d'autorité de certification.

      --service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
  --ssl-ca-file=SSL_CA_FILEPATH

    Où :

    • PROJECT_ID correspond à votre ID de projet Google Cloud.
    • REGION est la région de votre connexion.
    • NAMESPACE est l'espace de noms de votre service.
    • SERVICE_NAME est le nom de votre service dans votre espace de noms.
    • SSL_CA_FILEPATH est le chemin d'accès au fichier de votre certificat CA.

Vous venez de créer une connexion GitHub Enterprise.

Étapes suivantes