Crie uma associação a um anfitrião do GitHub Enterprise

Esta página explica como associar um anfitrião do GitHub Enterprise ao Cloud Build.

Antes de começar

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

Autorizações de IAM necessárias

Para associar o seu anfitrião do GitHub Enterprise, conceda a função de administrador da ligação do Cloud Build (roles/cloudbuild.connectionAdmin) à sua conta de utilizador.

Para adicionar as funções necessárias à sua conta de utilizador, consulte o artigo Configurar o acesso aos recursos do Cloud Build. Para saber mais sobre as funções de IAM associadas ao Cloud Build, consulte o artigo Funções e autorizações de IAM.

Para criar associações através dos passos de instalação do gcloud, conceda a função de administrador do Secret Manager (roles/secretmanager.admin) ao agente de serviço do Cloud Build executando o seguinte comando no seu projeto 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"

Se a sua instância do GitHub Enterprise estiver alojada numa rede privada, consulte o artigo Crie repositórios a partir do GitHub Enterprise numa rede privada para saber mais sobre as funções adicionais do IAM necessárias antes da associação do anfitrião.

Crie uma associação a um anfitrião do GitHub Enterprise

Consola

Para associar o seu anfitrião do GitHub Enterprise ao Cloud Build:

  1. Abra a página Repositórios na Google Cloud consola.

    Abra a página Repositórios

    É apresentada a página Repositórios.

  2. No seletor de projetos na barra superior, selecione o seu Google Cloud projeto.

  3. Na parte superior da página, selecione o separador 2.ª geração.

  4. Clique em Criar associação de anfitrião para associar um novo anfitrião ao Cloud Build.

  5. No painel do lado esquerdo, selecione GitHub Enterprise como fornecedor de origem.

  6. Na secção Configurar associação, introduza as seguintes informações:

    1. Região: selecione uma região para a sua associação.

    2. Nome: introduza um nome para a ligação.

  7. Na secção Detalhes do anfitrião, introduza as seguintes informações:

    1. URL do anfitrião: introduza o URL do anfitrião para a sua ligação. Por exemplo, github.example.com

    2. Certificado da AC: clique em Procurar para carregar o seu certificado autoassinado.

    3. Em Tipo de associação, selecione uma das seguintes opções:

      1. Internet pública: selecione esta opção se a sua instância for acessível através da Internet pública.

      2. Acesso à rede privada: selecione esta opção se a sua instância estiver alojada numa rede privada.

      3. Em Serviço de diretório de serviços, selecione a localização do seu serviço:

        • No projeto your-project
        • Noutro projeto
        • Introduza manualmente

        1. Se selecionar Noutro projeto ou Introduzir manualmente, introduza as seguintes informações:

          • Projeto: introduza ou selecione o seu Google Cloud ID do projeto no menu pendente.

          • Região: este campo pré-seleciona a região da sua ligação. A região especificada para o seu serviço tem de corresponder à região associada à sua ligação.

        2. Espaço de nomes: selecione o espaço de nomes do seu serviço.

        3. Serviço: selecione o nome do serviço no seu espaço de nomes.

  8. Clique em Ligar.

    Depois de clicar no botão Associar, é-lhe pedido que crie uma app GitHub no seu anfitrião do GitHub Enterprise e instale a app numa conta de utilizador ou numa organização. É criado um token de autenticação do seu anfitrião do GitHub Enterprise e armazenado neste projeto como um segredo do Secret Manager. Pode revogar o acesso desinstalando ou eliminando a app GitHub do seu anfitrião em qualquer altura.

    O Cloud Build armazena os dados de autenticação da app GitHub criada como segredos no Secret Manager no seu projeto. Estes dados incluem a sua chave privada e o segredo do webhook. A chave privada é usada como um método de autenticação para aceder à API do servidor empresarial. O segredo do webhook é usado para validar os eventos enviados do servidor para o Cloud Build. A conta do agente de serviço do Cloud Build (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) é usada para aceder ao seu segredo. Para ver o seu segredo, consulte o artigo Liste segredos e veja detalhes de segredos.

    Depois de autorizar a app GitHub do Cloud Build, é feito o redirecionamento para a página Repositórios do Cloud Build.

gcloud

Para associar o seu anfitrião do GitHub Enterprise ao Cloud Build através de comandos gcloud, conclua os seguintes passos:

  1. Introduza o seguinte comando para criar uma associação do GitHub Enterprise:

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

    Onde:

    • CONNECTION_NAME é um nome para a ligação do anfitrião do GitHub Enterprise no Cloud Build.
    • HOST_URI é o URI da sua instância do GitHub Enterprise. Por exemplo, https://mmy-ghe-server.net.
    • REGION é a região da sua ligação.

    Se a sua instância do GitHub Enterprise estiver numa rede privada, especifique o seu recurso do Service Directory. Também pode especificar o seu certificado da AC.

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

    Onde:

    • PROJECT_ID é o ID do seu Google Cloud projeto.
    • REGION é a região da sua ligação.
    • NAMESPACE é o espaço de nomes do seu serviço.
    • SERVICE_NAME é o nome do seu serviço no seu espaço de nomes.
    • SSL_CA_FILEPATH é o caminho para o seu certificado da CA.

    Depois de executar o comando gcloud builds connections..., recebe um link para instalar a app GitHub do Cloud Build.

  2. Siga o link devolvido no passo anterior para criar e instalar a app GitHub do Cloud Build no seu servidor empresarial.

  3. Introduza o seguinte comando para validar a sua ligação:

    gcloud builds connections describe CONNECTION_NAME --region=REGION

    Onde:

    • CONNECTION_NAME é o nome da ligação do anfitrião do GitHub Enterprise no Cloud Build.
    • REGION é a região da sua ligação.

    Se o campo installationState estiver definido como COMPLETE, significa que instalou a associação com êxito. Caso contrário, o campo installationState fornece um link para os passos adicionais necessários.

Associe a um anfitrião do GitHub Enterprise através de programação

Para associar o seu programa de alojamento do GitHub Enterprise ao Cloud Build de forma programática, tem de instalar a app GitHub concluindo os seguintes passos:

  1. Registe uma nova app GitHub. Por exemplo, pode registar uma nova app GitHub em https://my-ghe-server.net/settings/apps/new.

  2. Preencha os campos na página:

    1. Nome da app GitHub: introduza um nome para a sua app.
    2. URL da página inicial: introduza um URL para o seu GitHub Enterprise Server.
    3. Desmarque a caixa As chaves de autorização do utilizador expiram.
    4. Na secção Webhook, conclua os seguintes passos:
      • Ativo: selecione a caixa para ativar o webhook.
      • URL do webhook: introduza o URL do webhook. Por exemplo, https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook. A região no URL do webhook tem de corresponder à região da sua associação.
      • Segredo do webhook: introduza uma string gerada aleatoriamente e tome nota da mesma.
    5. Na secção Autorizações, especifique as seguintes autorizações:
      • Autorizações do repositório:
        • Cheques: leitura e escrita
        • Conteúdos: leitura e escrita
        • Problemas: só de leitura
        • Metadados só de leitura
        • Estados de confirmação: só de leitura
        • Pedidos de envio: só de leitura
    6. Na secção Subscrever eventos, selecione as seguintes caixas:
      • Verificar execução
      • Conjunto de verificações
      • Enviar comentário
      • Comentar problema
      • Pedido de envio
      • Comentário de revisão do pedido de envio
      • Push
      • Repositório
    7. Selecione a caixa Qualquer conta para permitir que a sua app GitHub seja instalada por qualquer utilizador ou organização.

  3. Clique em Criar app GitHub para criar a sua app GitHub.

    Depois de clicar em Criar app GitHub, é feito o redirecionamento para a página da app. Tome nota do ID da app e do slug da app. Pode encontrar o slug da app no último segmento do URL da página. Por exemplo, https://my-ghe-server.net/settings/apps/{app-slug}

  4. Na secção Chaves privadas, clique em Gerar uma chave privada.

    Armazene o ficheiro transferido num local seguro.

  5. No painel esquerdo, selecione Instalar app.

    Selecione o utilizador ou a organização onde quer instalar a app. Após a instalação da app, tome nota do ID de instalação. Pode encontrar o ID de instalação no último segmento do URL da página. Por exemplo, https://my-ghe-server.net/settings/installations/{installation-id}.

Depois de instalar a app GitHub, conclua os seguintes passos para associar o seu anfitrião do GitHub Enterprise de forma programática através do Terraform ou gcloud.

Terraform

Depois de instalar a app GitHub, pode associar o seu anfitrião do GitHub Enterprise ao Cloud Build através do fornecedor Google Terraform.

No exemplo seguinte, o fragmento do código faz o seguinte:

  • Configura o fornecedor Google do Terraform
  • Cria um segredo para armazenar a chave privada e o segredo do webhook da app GitHub
  • Concede as autorizações necessárias ao agente de serviço do Cloud Build para aceder a segredos

  • Cria uma ligação ao 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
    ]
}

Onde:

  • PROJECT_ID é o ID do seu Google Cloud projeto.
  • PRIVATE_KEY_SECRET é o segredo que contém a chave privada da sua app GitHub.
  • WEBHOOK_SECRET é o nome do segredo que contém o valor do segredo do webhook da sua app GitHub.
  • WEBHOOK_SECRET_VALUE é o valor do segredo do webhook da sua app GitHub.
  • REGION é a região da sua ligação.
  • CONNECTION_NAME é um nome para a ligação do anfitrião do GitHub Enterprise no Cloud Build.
  • URI é o URI da sua ligação. Por exemplo, https://my-github-enterprise-server.net.
  • APP_ID é o ID da sua app GitHub.
  • APP_SLUG é o slug da app. Por exemplo, https://github.com/settings/apps/{app-slug}.
  • INSTALLATION_ID é o ID de instalação da sua app GitHub. Pode encontrar o ID de instalação no URL da sua app GitHub do Cloud Build, https://github.com/settings/installations/{installation-id}.

gcloud

Depois de instalar a app GitHub, conclua os seguintes passos para associar o seu anfitrião do GitHub Enterprise de forma programática através de gcloud:

  1. Armazene os seus segredos no 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

    Onde:

    • WEBHOOK_SECRET é a string que criou para o segredo do webhook.
    • PRIVATE_KEY_FILE é o caminho para a chave privada que gerou.

  2. Conceda acesso ao agente de serviço do Cloud Build para aceder aos seus segredos:

    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"

    Onde:

    • PROJECT_ID é o ID do seu Google Cloud projeto.
    • CLOUD_BUILD_SERVICE_AGENT é a sua conta por produto e por projeto.

  3. Crie a sua associação ao 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

    Onde:

    • CONNECTION_NAME é um nome para a ligação do anfitrião do GitHub Enterprise no Cloud Build.
    • HOST_URI é o URI da sua instância do GitHub Enterprise. Por exemplo, https://mmy-ghe-server.net.
    • APP_ID é o ID da sua app GitHub.
    • APP_SLUG é o slug da app. Por exemplo, https://my-ghe-server.net/settings/apps/app-slug.
    • PROJECT_ID é o ID do seu Google Cloud projeto.
    • INSTALLATION_ID é o ID de instalação da sua app GitHub. Por exemplo: https://my-ghe-server.net/settings/installations/installation-id
    • REGION é a região da sua ligação.

    Se a sua instância do GitHub Enterprise estiver numa rede privada, especifique o seu recurso do Service Directory. Também pode especificar o seu certificado da AC.

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

    Onde:

    • PROJECT_ID é o ID do seu Google Cloud projeto.
    • REGION é a região da sua ligação.
    • NAMESPACE é o espaço de nomes do seu serviço.
    • SERVICE_NAME é o nome do seu serviço no seu espaço de nomes.
    • SSL_CA_FILEPATH é o caminho para o seu certificado da CA.

Passos seguintes