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 la page Rôles et autorisations IAM.

Pour créer des connexions à l'aide des étapes d'installation gcloud, attribuez 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 sur 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 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 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 de 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
        • Saisir manuellement

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

          • Project (Projet) : saisissez ou sélectionnez votre Google Cloud ID de projet 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 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. 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 dans votre projet. Ces données incluent votre clé privée et votre secret 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 Lister les secrets et afficher leurs détails.

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

Vous avez maintenant créé une connexion GitHub Enterprise.

gcloud

Pour connecter votre hôte GitHub Enterprise à Cloud Build à l'aide de 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.
    • 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 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 Google Cloud projet.
    • 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 correspond au chemin d'accès au fichier de votre autorité de certification.

    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 d'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 avez maintenant créé 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 une nouvelle application GitHub sur 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 :
      • Active: 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 à 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 :
        • Contrôles: 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 :
      • Exécuter le contrôle
      • Suite de vérifications
      • Commentaire de commit
      • Envoyer un commentaire
      • Demande d'extraction
      • Commentaire d'examen d'une 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é dans un emplacement sécurisé.

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

    Sélectionnez l'utilisateur ou l'organisation dans laquelle 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 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 Google Cloud projet.
  • 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 avez maintenant créé 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 votre secret de 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 est l'ID de votre Google Cloud projet.
    • 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 correspond au slug de l'application. Exemple :https://my-ghe-server.net/settings/apps/app-slug
    • PROJECT_ID est l'ID de votre Google Cloud projet.
    • 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 est l'ID de votre Google Cloud projet.
    • REGION est la région de votre connexion.
    • NAMESPACE correspond à l'espace de noms de votre service.
    • SERVICE_NAME est le nom de votre service dans votre espace de noms.
    • SSL_CA_FILEPATH correspond au chemin d'accès au fichier de votre autorité de certification.

Vous avez maintenant créé une connexion GitHub Enterprise.

Étapes suivantes