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 la page Configurer l'accès aux ressources Cloud Build. Pour en savoir plus sur les rôles IAM associés à Cloud Build, consultez Rôles et autorisations IAM.

Pour créer des connexions à l'aide des étapes d'installation de gcloud, accordez le rôle 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 dans un réseau privé, consultez Créer des dépôts à partir de GitHub Enterprise dans un réseau privé pour en savoir plus sur les rôles IAM supplémentaires requis avant la connexion de l'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 dans 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 Configurer la connexion, saisissez les informations suivantes :

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

    2. Nom : saisissez un nom pour votre connexion.

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

    1. 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 dans un réseau privé.

      3. Sous Service 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 les informations suivantes :

          • 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. La région spécifiée pour votre service doit correspondre à celle 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 Associer, vous serez invité à créer une application GitHub sur votre hôte GitHub Enterprise et à l'installer dans un compte utilisateur ou une organisation. Un jeton d'authentification associé à votre hôte GitHub Enterprise sera créé et stocké dans ce projet 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 de l'application GitHub créée en tant que secrets dans Secret Manager de votre projet. Ces données incluent votre clé privée et le secret du webhook. La clé privée est utilisée comme méthode d'authentification pour accéder à l'API Enterprise Server. Le secret du 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) est utilisé pour accéder à votre secret. Pour afficher votre secret, consultez Lister les secrets et afficher leurs détails.

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

gcloud

Pour connecter votre hôte GitHub Enterprise à Cloud Build à l'aide des commandes 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 hôte GitHub Enterprise dans Cloud Build.
    • 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 dans un réseau privé, spécifiez votre ressource Annuaire des 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 est l'ID de votre 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 à votre certificat CA.

    Après avoir exécuté la commande gcloud builds connections..., vous recevrez un lien pour installer l'application GitHub Cloud Build.

  2. Suivez le lien renvoyé à l'étape précédente pour créer et installer l'application GitHub Cloud Build sur votre serveur Enterprise.

  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 hôte GitHub Enterprise dans Cloud Build.
    • REGION est la région de votre connexion.

    Si le champ installationState est défini sur COMPLETE, vous avez correctement installé la connexion. Sinon, le champ installationState fournit un lien vers les étapes supplémentaires requises.

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 application GitHub. Par exemple, vous pouvez enregistrer une application GitHub à l'adresse https://my-ghe-server.net/settings/apps/new.

  2. Remplissez les champs de la page :

    1. Nom de l'application GitHub : saisissez le nom de votre application.
    2. URL de la page d'accueil : saisissez l'URL de votre serveur GitHub Enterprise.
    3. Décochez la case Expiration des jetons d'autorisation des utilisateurs.
    4. Dans la section Webhook, procédez comme suit :
      • Actif : cochez la case pour activer votre webhook.
      • 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 à celle de votre connexion.
      • Secret de 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 :
        • Checks : lecture et écriture
        • Contenus : 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 :
      • Exécuter un test
      • Suite Check
      • Commentaire de commit
      • Commentaire sur le problème
      • Demande d'extraction
      • Commentaire d'examen de la demande d'extraction
      • Push
      • Dépôt
    7. Cochez la case Tout compte pour autoriser tout utilisateur ou organisation à installer votre application GitHub.

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

    Une fois que vous avez cliqué sur Créer une application GitHub, vous êtes redirigé vers la page de votre application. Notez votre ID d'application et le slug de l'application. 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é dans un endroit sûr.

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

    Sélectionnez l'utilisateur ou l'organisation pour 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}.

Une fois votre application GitHub installée, suivez les étapes ci-dessous pour connecter votre hôte GitHub Enterprise de manière programmatique à l'aide de Terraform ou 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 de webhook de l'application GitHub
  • Accorde les autorisations nécessaires à l'agent de service Cloud Build 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 est l'ID de votre projet Google Cloud .
  • PRIVATE_KEY_SECRET est le secret contenant la clé privée de votre application GitHub.
  • WEBHOOK_SECRET est le nom 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 hôte GitHub Enterprise dans Cloud Build.
  • 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 trouverez votre ID d'installation dans l'URL de votre application GitHub Cloud Build, https://github.com/settings/installations/{installation-id}.

gcloud

Une fois votre application GitHub installée, 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 votre secret de webhook.
    • PRIVATE_KEY_FILE correspond au chemin d'accès à la clé privée que vous avez générée.

  2. Accordez l'accès à l'agent de service Cloud Build pour accéder à 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 est l'ID de votre 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 hôte GitHub Enterprise dans Cloud Build.
    • 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 correspond au slug de l'application. Exemple :https://my-ghe-server.net/settings/apps/app-slug
    • PROJECT_ID est l'ID de votre 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 dans un réseau privé, spécifiez votre ressource Annuaire des 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 est l'ID de votre 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 à votre certificat CA.

Étapes suivantes