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, accordez à l'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 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 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, procédez comme suit:

  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 2nd gen (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 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 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 l'Annuaire des 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 dans votre GitHub Enterprise héberge et installe l'application dans un compte utilisateur ou une organisation. Une 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 du webhook sert à valider envoyés par le serveur à Cloud Build. Cloud Build Compte d'agent de service (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 les dépôts 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 Annuaire des 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 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 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 indique un lien vers les étapes supplémentaires requises.

Vous avez maintenant créé une connexion GitHub Enterprise.

Se connecter par programmation à un hôte GitHub Enterprise

Pour connecter votre hôte GitHub Enterprise de manière automatisée à Cloud Build, procédez comme suit : 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. GitHub App Name (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 l'option Expire user authorization tokens (Expirer les jetons d'autorisation utilisateur).
    4. Dans la section Webhook, procédez comme suit: <ph type="x-smartling-placeholder">
        </ph>
      • 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: <ph type="x-smartling-placeholder">
        </ph>
      • Autorisations du dépôt: <ph type="x-smartling-placeholder">
          </ph>
        • Contrôles : lecture et écriture
        • Sommaire: Lecture et écriture
        • Problèmes: lecture seule
        • Métadonnées : lecture seule
        • États de commit: Lecture seule
        • Pull requests : lecture seule
    6. Dans la section S'abonner aux événements, cochez les cases suivantes: <ph type="x-smartling-placeholder">
        </ph>
      • Vérifier l'exécution
      • Vérifier la suite
      • Commentaire sur le commit
      • Commentaire sur le problème
      • Demande d'extraction
      • Commentaire d'examen d'une demande d'extraction
      • Pousser
      • 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 cliquerez sur Créer une application GitHub, vous serez redirigé vers la page de votre application. Prenez note de votre ID d'application et de son slug. Le slug d'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 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 via le fournisseur Terraform pour Google.

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

  • Il configure le fournisseur Terraform pour Google
  • 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 du secret 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 est l'ID d'installation de votre application GitHub. Votre l'ID d'installation se trouve dans l'URL de votre Application GitHub, 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 connectez votre hôte GitHub Enterprise de manière automatisée à 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 est le chemin d'accès à 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 correspond au 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 Annuaire des 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 CA.

Vous avez maintenant créé une connexion GitHub Enterprise.

Étapes suivantes