Conectar-se a um host do GitHub Enterprise

Nesta página, explicamos como conectar um host do GitHub Enterprise ao Cloud Build.

Antes de começar

  • Ative as APIs Cloud Build e Secret Manager, se alguma delas ainda não estiver ativada.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar as APIs

Permissões do IAM obrigatórias

Para conectar seu host do GitHub Enterprise, conceda o papel de Administrador de conexão do Cloud Build (roles/cloudbuild.connectionAdmin) à sua conta de usuário.

Para adicionar os papéis necessários à sua conta de usuário, consulte Configurar o acesso aos recursos do Cloud Build. Para saber mais sobre os papéis do IAM associados ao Cloud Build, consulte Papéis e permissões do IAM.

Para criar conexões usando as etapas de instalação do gcloud, conceda o papel de administrador do Secret Manager (roles/secretmanager.admin) ao agente de serviço do Cloud Build executando o seguinte comando no 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 instância do GitHub Enterprise estiver hospedada em uma rede particular, consulte Criar repositórios do GitHub Enterprise em uma rede particular para conhecer outras funções do IAM necessárias antes da conexão do host.

Conectar a um host do GitHub Enterprise

Console

Para conectar seu host do GitHub Enterprise ao Cloud Build:

  1. Abra a página Repositórios no console do Google Cloud .

    Abrir a página Repositórios

    A página Repositórios vai aparecer.

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

  3. Na parte de cima da página, selecione a guia 2ª geração.

  4. Clique em Criar conexão de host para conectar um novo host ao Cloud Build.

  5. No painel à esquerda, selecione GitHub Enterprise como seu provedor de origem.

  6. Na seção Configurar conexão, insira as seguintes informações:

    • Região: selecione uma região para sua conexão.

    • Nome: insira um nome para sua conexão.

  7. Na seção Detalhes do host, acesse URL do host e insira o URL do host da sua conexão. Por exemplo, github.example.com.

  8. Opcional: se você quiser gerenciar as chaves de criptografia usadas para criptografar os tokens de acesso dos repositórios do GitHub Enterprise, acesse a seção Criptografia e escolha uma chave do Cloud Key Management Service. Para mais informações, consulte Ativar chaves de criptografia gerenciadas pelo cliente para o Secret Manager.

  9. Na seção Rede, em Tipo de conexão, selecione uma das seguintes opções:

    • Internet pública: selecione essa opção se a instância puder ser acessada usando a Internet pública.

    • Rede particular: selecione essa opção se a instância estiver hospedada em uma rede particular. Em seguida, configure o seguinte:

      1. Certificado da CA: clique em "Procurar" para fazer upload do seu certificado autoassinado.

      2. Em Serviço do Service Directory, selecione o local do seu serviço:

        • No projeto CURRENT_PROJECT
        • Em outro projeto
        • Inserir manualmente

      3. Digite as seguintes informações:

        • Projeto: se você selecionou Em outro projeto ou Inserir manualmente, insira ou selecione o ID do projeto Google Cloud no menu suspenso.

        • Região: esse campo pré-seleciona a região da sua conexão. A região especificada para o serviço precisa corresponder à região associada à conexão.

        • Namespace: selecione o namespace do seu serviço.

        • Serviço: selecione o nome do serviço no namespace.

  10. Clique em Conectar.

    Depois de clicar no botão Conectar, você precisará criar um app do GitHub no host do GitHub Enterprise e instalá-lo em uma conta de usuário ou organização. Um token de autenticação do host do GitHub Enterprise é criado e armazenado neste projeto como um secret do Secret Manager. Para revogar o acesso, desinstale ou exclua o app GitHub do seu host.

    O Cloud Build armazena os dados de autenticação do app GitHub criado como secrets no Secret Manager do seu projeto. Esses dados incluem sua chave privada e o segredo do webhook. A chave privada é usada como um método de autenticação para acessar a API do Enterprise Server. A chave secreta do webhook é usada 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 acessar seu secret. Para conferir seu secret, consulte Listar secrets e conferir os detalhes do secret.

    Depois de autorizar o app GitHub do Cloud Build, você será redirecionado para a página Repositórios do Cloud Build.

gcloud

Para conectar seu host do GitHub Enterprise ao Cloud Build usando comandos gcloud, siga estas etapas:

  1. Insira o comando a seguir para criar uma conexão do GitHub Enterprise:

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

    Em que:

    • CONNECTION_NAME é um nome para sua conexão de host 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 conexão.

    Se a instância do GitHub Enterprise estiver em uma rede particular, especifique o recurso do Diretório de serviços. Também é possível especificar o certificado de CA.

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

    Em que:

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

    Depois de executar o comando gcloud builds connections..., você vai receber um link para instalar o app GitHub do Cloud Build.

  2. Siga o link retornado na etapa anterior para criar e instalar o app do GitHub do Cloud Build no seu servidor empresarial.

  3. Digite o seguinte comando para verificar sua conexão:

    gcloud builds connections describe CONNECTION_NAME --region=REGION

    Em que:

    • CONNECTION_NAME é o nome da sua conexão de host do GitHub Enterprise no Cloud Build.
    • REGION é a região da sua conexão.

    Se o campo installationState estiver definido como COMPLETE, a conexão foi instalada. Caso contrário, o campo installationState fornece um link para as etapas adicionais necessárias.

Conectar-se a um host do GitHub Enterprise de maneira programática

Para conectar seu host do GitHub Enterprise ao Cloud Build de maneira programática, instale o app GitHub seguindo estas etapas:

  1. Registre um novo app do GitHub. Por exemplo, você pode registrar um novo app do GitHub em https://my-ghe-server.net/settings/apps/new.

  2. Preencha os campos na página:

    1. Nome do app GitHub: insira um nome para o app.
    2. URL da página inicial: insira um URL para o GitHub Enterprise Server.
    3. Desmarque a caixa Expirar tokens de autorização do usuário.
    4. Na seção Webhook, siga estas etapas:
      • Ativo: marque a caixa para ativar o webhook.
      • URL do webhook: insira 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 precisa corresponder à região da sua conexão.
      • Secret do webhook: insira uma string gerada aleatoriamente e anote-a.
    5. Na seção Permissões, especifique as seguintes permissões:
      • Permissões do repositório:
        • Verificações: leitura e gravação
        • Conteúdo: leitura e gravação
        • Problemas: somente leitura
        • Metadados somente leitura
        • Status de confirmação: somente leitura
        • Solicitações de envio: somente leitura
    6. Na seção Inscrever-se em eventos, marque as seguintes caixas:
      • Executar verificação
      • Pacote de verificações
      • Comentário de commit
      • Comentar problema
      • Solicitação de pull
      • Comentário de análise de solicitação de pull
      • Push
      • Repositório
    7. Marque a caixa Qualquer conta para permitir que seu app do GitHub seja instalado por qualquer usuário ou organização.

  3. Clique em Criar app do GitHub.

    Ao clicar em Criar app do GitHub, você será redirecionado para a página do app. Anote o ID e o slug do app. O slug do app pode ser encontrado no último segmento do URL da página. Por exemplo, https://my-ghe-server.net/settings/apps/{app-slug}

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

    Armazene o arquivo baixado em um local seguro.

  5. No painel à esquerda, selecione Instalar app.

    Selecione o usuário ou a organização em que você quer instalar o app. Depois da instalação, anote o ID de instalação. O ID de instalação pode ser encontrado no último segmento do URL da página. Por exemplo, https://my-ghe-server.net/settings/installations/{installation-id}

Depois de instalar o app GitHub, siga estas etapas para conectar o host do GitHub Enterprise de maneira programática usando o Terraform ou gcloud.

Terraform

Depois de instalar o app GitHub, conecte o host do GitHub Enterprise ao Cloud Build usando o provedor Google Terraform.

No exemplo a seguir, o snippet de código faz o seguinte:

  • Configura o provedor do Google para Terraform.
  • Cria um secret para armazenar a chave privada e o secret do webhook do app GitHub.
  • Concede as permissões necessárias ao agente de serviço do Cloud Build para acessar secrets.

  • Cria uma conexão do 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
    ]
}

Em que:

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

gcloud

Depois de instalar o app GitHub, conclua as etapas a seguir para conectar o host do GitHub Enterprise de maneira programática usando gcloud:

  1. Armazene seus secrets 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

    Em que:

    • WEBHOOK_SECRET é a string criada para o secret do webhook.
    • PRIVATE_KEY_FILE é o caminho para a chave privada que você gerou.

  2. Conceda acesso ao agente de serviço do Cloud Build para acessar seus 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"

    Em que:

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

  3. Crie sua conexão do 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

    Em que:

    • CONNECTION_NAME é um nome para sua conexão de host 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 do seu app GitHub.
    • APP_SLUG é o slug do app. Por exemplo, https://my-ghe-server.net/settings/apps/app-slug.
    • PROJECT_ID é o ID do projeto Google Cloud .
    • INSTALLATION_ID é o ID de instalação do seu app GitHub. Por exemplo, https://my-ghe-server.net/settings/installations/installation-id
    • REGION é a região da sua conexão.

    Se a instância do GitHub Enterprise estiver em uma rede particular, especifique o recurso do Diretório de serviços. Também é possível especificar o certificado de CA.

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

    Em que:

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

Girar tokens de acesso do GitHub Enterprise

Faça a rotação dos tokens de acesso para que a conexão de host do Cloud Build mantenha a conexão com o repositório do GitHub Enterprise. Se o token de acesso do GitHub Enterprise expirar, a conexão do host do Cloud Build será desconectada do repositório do GitHub Enterprise. Quando isso acontece, não é possível desativar a conexão nem vincular um repositório até girar o token expirado. Além disso, você vai encontrar erros nas seguintes circunstâncias:

  • A página Detalhes da conexão mostra uma mensagem de erro Resolver problemas de conexão ou Instalação do app GitHub não encontrada. As duas mensagens têm um botão Gerenciar instalação.

  • Se você tentar vincular um repositório a uma conexão com um token expirado, a mensagem Token de acesso inválido vai aparecer. Ao clicar em Ver conexão, você acessa a página Detalhes da conexão da conexão com o token expirado.

Tokens de acesso do GitHub Enterprise expirados ou inválidos não podem ser rotacionados em uma conexão do Cloud Build, e essa conexão não pode mais ser usada. Para conferir informações no GitHub Enterprise sobre o status do seu repositório e dos tokens, faça o seguinte:

  1. Na página Detalhes da conexão, clique em Resolver problemas.

  2. No menu Resolver problemas de conexão, clique em Gerenciar instalação.

    O Cloud Build abre a página do GitHub Enterprise para suas instalações.

Próximas etapas