Se connecter à un hôte GitHub Enterprise

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

Avant de commencer

Activer les API Cloud Build and Secret Manager.
Activer les API

Assurez-vous de disposer de la dernière version de GitHub Enterprise.
Assurez-vous de mapper un domaine personnalisé à votre hôte GitHub Enterprise et de disposer d'un certificat SSL valide pour votre hôte.

Remarque: Si votre hôte GitHub Enterprise s'exécute sur une instance Compute Engine, vous pouvez créer un équilibreur de charge HTTP(S) externe. et utilisez un certificat SSL géré par Google pour votre instance.
Si votre instance GitHub Enterprise est hébergée dans un réseau privé, consultez la section Créer des dépôts à partir de GitHub Enterprise dans un réseau privé avant de suivre les instructions de cette page.

Autorisations IAM requises

Pour connecter votre hôte GitHub Enterprise, accordez 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, attribuez 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 la section Créer des dépôts GitHub Enterprise dans un réseau privé pour en savoir plus sur les rôles IAM supplémentaires requis avant la connexion à l'hôte.

Se connecter à un hôte GitHub Enterprise

Console

Pour connecter votre hôte GitHub Enterprise à Cloud Build, procédez comme suit:

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

Ouvrir la page "Dépôts"

La page Dépôts s'affiche.
Dans le sélecteur de projet de la barre supérieure, sélectionnez votre projet Google Cloud.
En haut de la page, sélectionnez l'onglet 2nd gen (2e génération).
Cliquez sur Créer une connexion hôte pour connecter un nouvel hôte à Cloud Build.
Dans le panneau de gauche, sélectionnez GitHub Enterprise comme fournisseur source.
Dans la section Configure Connection (Configurer la connexion), saisissez les informations suivantes:
1. Région: sélectionnez une région pour votre connexion.
  
  Remarque :Vous devez spécifier une région. Votre connexion n'existe pas dans le monde entier.
2. Name (Nom) : saisissez le nom de votre connexion.
Dans la section 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 de votre connexion. Par exemple, github.example.com.
2. Certificat CA: cliquez sur "Parcourir" pour importer votre certificat autosigné.
  
  Remarque :Votre certificat ne doit pas dépasser 10 Ko et doit être au format PEM (.pem, .cer ou .crt). Si cette section est laissée vide, un ensemble de certificats par défaut sera utilisé.
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 les informations suivantes:
      - Project (Projet) : saisissez ou sélectionnez l'ID de votre projet Google Cloud dans le menu déroulant.
      - Region (Région) : ce champ présélectionne la région de votre connexion. La région spécifiée pour votre service 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.
Cliquez sur Connect (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 de 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 code secret du webhook. La clé privée est utilisée comme méthode d'authentification pour accéder à l'API d'Enterprise Server. Le code secret du webhook permet de valider les événements envoyés par le serveur à Cloud Build. Le compte d'agent de service Cloud Build (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) permet d'accéder à votre secret. Pour afficher le secret, consultez la section Répertorier les secrets et afficher les détails du secret.

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

Vous avez créé une connexion GitHub Enterprise.

gcloud

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

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. Par 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 d'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 de votre service dans votre espace de noms.
- SSL_CA_FILEPATH est le chemin d'accès au fichier de certificat CA.
Après avoir exécuté la commande gcloud builds connections..., vous recevrez un lien pour installer l'application GitHub Cloud Build.
Suivez le lien renvoyé à l'étape précédente pour créer et installer l'application GitHub Cloud Build sur votre serveur d'entreprise.
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 créé une connexion GitHub Enterprise.

Se connecter de manière automatisée à un hôte GitHub Enterprise

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

Enregistrez une nouvelle application GitHub. Par exemple, vous pouvez enregistrer une nouvelle application GitHub sur https://my-ghe-server.net/settings/apps/new.
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 la case Expire user authorization tokens (Expiration des jetons d'autorisation utilisateur).
4. Dans la section Webhook, procédez comme suit :
  - Actif: cochez cette case pour activer votre webook.
  - URL de webhook: saisissez l'URL de webhook. Par exemple, https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook. La région de l'URL de webhook doit correspondre à celle de votre connexion.
  - Code secret du webhook: saisissez une chaîne générée de manière aléatoire et prenez-en note.
5. Dans la section Autorisations, spécifiez les autorisations suivantes :
  - Autorisations liées au dépôt :
    - Vérifications: lecture et écriture
    - Sommaire: Lecture et écriture
    - Problèmes: lecture seule
    - Métadonnées : lecture seule
    - États de commit: lecture seule
    - Demandes d'extraction: lecture seule
6. Dans la section S'abonner aux événements, cochez les cases suivantes :
  - Exécution du test
  - Vérifier la suite
  - Valider le commentaire
  - Commentaire concernant le problème
  - Demande d'extraction
  - Commentaire concernant l'examen de la demande d'extraction
  - Pousser
  - Dépôt
7. Cochez la case Any account (Tous les comptes) pour permettre à tous les utilisateurs ou organisations d'installer votre application GitHub.
Cliquez sur Créer une application GitHub pour créer votre application GitHub.

Après avoir cliqué sur Créer une application GitHub, vous serez redirigé vers la page de votre application. Notez l'ID de votre application et le slug de l'application. 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}.
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.
Dans le volet de gauche, sélectionnez Install App (Installer l'application).

Sélectionnez l'utilisateur ou l'organisation dans lequel 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 automatisée à l'aide de Terraform ou de gcloud.

Terraform

Une fois que vous avez installé votre application GitHub, 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:

Il configure le fournisseur Terraform pour Google
Crée un secret pour stocker la clé privée et le code 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 {
        automatic = true
    }
}

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 {
        automatic = true
    }
}

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 de 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. Par exemple, https://my-github-enterprise-server.net.
APP_ID est l'ID de votre application GitHub.
APP_SLUG est le slug de l'application. Par exemple, https://github.com/settings/apps/{app-slug}.
INSTALLATION_ID est 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 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 automatisée à l'aide de gcloud:

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 du fichier à la clé privée que vous avez générée.

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 correspond à votre ID de projet Google Cloud.
CLOUD_BUILD_SERVICE_AGENT correspond à votre compte par produit et par projet.

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. Par exemple, https://mmy-ghe-server.net.
- APP_ID est l'ID de votre application GitHub.
- APP_SLUG est le slug de l'application. Par 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 dans un réseau privé, spécifiez votre ressource d'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 de votre service dans votre espace de noms.
- SSL_CA_FILEPATH est le chemin d'accès au fichier de certificat CA.

Vous avez créé une connexion GitHub Enterprise.

Étapes suivantes

Découvrez comment connecter un dépôt à GitHub Enterprise.
Découvrez comment effectuer des déploiements bleu-vert sur Compute Engine.