Esta página foi traduzida pela API Cloud Translation.

Conectar-se a um host do GitHub Enterprise

Esta página explica como conectar um host do GitHub Enterprise ao Cloud Build.

Antes de começar

Enable the Cloud Build and Secret Manager APIs.
Enable the APIs

Verifique se você tem a versão mais recente do GitHub Enterprise.
Certifique-se de mapear um domínio personalizado para seu host do GitHub Enterprise e de ter um certificado SSL válido para seu host.

Observação: se o host do GitHub Enterprise estiver em execução em uma instância do Compute Engine, será possível criar um balanceador de carga HTTP(S) externo, e usar um certificado SSL gerenciado pelo Google para sua instância.
Se a instância do GitHub Enterprise estiver hospedada em uma rede privada, consulte Criar repositórios do GitHub Enterprise em uma rede privada antes de seguir as instruções desta página.

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 à conta de usuário, consulte Como 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 privada, consulte Criar repositórios do GitHub Enterprise em uma rede privada para saber mais sobre as outras funções do IAM necessárias antes da conexão do host.

Como se conectar a um host do GitHub Enterprise

Console

Para conectar o host do GitHub Enterprise ao Cloud Build:

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

Abrir a página Repositórios

Você vai encontrar a página Repositórios.
No seletor de projetos, na barra superior, selecione seu projeto do Google Cloud.
Na parte de cima da página, selecione a guia 2ª geração.
Clique em Criar conexão de host para conectar um novo host ao Cloud Build.
No painel à esquerda, selecione GitHub Enterprise como provedor de origem.
Na seção Configurar conexão, insira as seguintes informações:
1. Região: selecione uma região para a conexão.
  
  Observação: é necessário especificar uma região. Sua conexão não pode existir globalmente.
2. Nome: insira um nome para a conexão.
Na seção Detalhes do host, insira as seguintes informações:
1. URL do host: insira o URL do host da sua conexão. Por exemplo, github.example.com
2. Certificado de AC: clique em Procurar para fazer upload do certificado autoassinado.
  
  Observação: o certificado não pode exceder 10 KB e precisa estar no formato PEM (.pem, .cer ou .crt). Se esta seção for deixada em branco, um conjunto padrão de certificados será usado no lugar.
3. Em Tipo de conexão, selecione uma das seguintes opções:
  1. Internet pública: selecione essa opção se a instância for acessível pela Internet pública.
  2. Acesso de rede particular: selecione essa opção se a instância estiver hospedada em uma rede particular.
  3. Em Serviço do diretório de serviços, selecione o local do seu serviço:
    - No projeto your-project
    - Em outro projeto
    - Inserir manualmente
    1. Se você selecionar Em outro projeto ou Inserir manualmente, insira as seguintes informações:
      - Project: insira ou selecione o ID do Google Cloud projeto 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.
    2. Namespace: selecione o namespace do serviço.
    3. Serviço: selecione o nome do serviço no seu namespace.
Clique em Conectar.

Depois de clicar no botão Conectar, você vai precisar criar um app GitHub no seu 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 será criado e armazenado neste projeto como um secret do Secret Manager. Para revogar o acesso, desinstale ou exclua o app GitHub do seu host a qualquer momento.

O Cloud Build armazena os dados de autenticação do app GitHub criado como secrets no Secret Manager no seu projeto. Esses dados incluem a chave privada e a chave secreta do webhook. A chave privada é usada como um método de autenticação para acessar a API do servidor corporativo. O secret do webhook é usado para validar os eventos enviados do servidor para o Cloud Build. A conta de agente de serviço do Cloud Build (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) é usada para acessar seu secret. Para conferir o 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.

Você criou uma conexão com o GitHub Enterprise.

gcloud

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

Digite o seguinte comando 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 é o nome da conexão.
- 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 da AC.
```
--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 Google Cloud projeto.
- 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 do arquivo para o certificado da AC.
Depois de executar o comando gcloud builds connections..., você vai receber um link para instalar o app Cloud Build GitHub.
Siga o link retornado na etapa anterior para criar e instalar o aplicativo Cloud Build do GitHub no seu servidor corporativo.
Digite o seguinte comando para verificar a conexão:
```
gcloud builds connections describe CONNECTION_NAME --region=REGION
```
Em que:
- CONNECTION_NAME é o nome da conexão.
- REGION é a região da sua conexão.
Se o campo installationState estiver definido como COMPLETE, a conexão terá sido instalada. Caso contrário, o campo installationState fornece um link para as etapas adicionais necessárias.

Você criou uma conexão com o GitHub Enterprise.

Como se conectar a um host do GitHub Enterprise de maneira programática

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

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.
Preencha os campos na página:
1. Nome do app do GitHub: insira um nome para o app.
2. URL da página inicial: insira um URL para o servidor do GitHub Enterprise.
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 webook.
  - 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 Assinar eventos, marque as seguintes caixas:
  - Verificar execução
  - Check suite
  - Comentário de confirmação
  - Comentário sobre o problema
  - Solicitação de envio
  - Comentário de análise de solicitação de envio
  - Push
  - Repositório
7. Marque a caixa Qualquer conta para permitir que o app do GitHub seja instalado por qualquer usuário ou organização.
Clique em Criar app GitHub para criar seu app GitHub.

Ao clicar em Criar app 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}
Na seção Chaves privadas, clique em Gerar uma chave privada.

Armazene o arquivo baixado em um local seguro.
No painel à esquerda, selecione Instalar app.

Selecione o usuário ou a organização em que você quer instalar o app. Depois que ele for instalado, 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 as etapas abaixo para conectar o host do GitHub Enterprise de maneira programática usando o Terraform ou gcloud.

Terraform

Depois de instalar o app GitHub, você pode conectar o host do GitHub Enterprise ao Cloud Build usando o provedor do Terraform do Google.

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

Configura o provedor do Google do 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 segredos

Cria uma conexão com o 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 Google Cloud projeto.
PRIVATE_KEY_SECRET é o segredo que contém a chave privada do app do GitHub.
WEBHOOK_SECRET é o nome do secret que contém o valor do secret do webhook do app do GitHub.
WEBHOOK_SECRET_VALUE é o valor do secret do webhook do app do GitHub.
REGION é a região da sua conexão.
CONNECTION_NAME é o nome da sua conexão do GitHub.
URI é o URI da sua conexão. Por exemplo, https://my-github-enterprise-server.net.
APP_ID é o ID do seu app do GitHub.
APP_SLUG é o slug do app. Por exemplo, https://github.com/settings/apps/{app-slug}.
INSTALLATION_ID é o ID de instalação do app GitHub. O ID de instalação pode ser encontrado no URL do app GitHub do Cloud Build, https://github.com/settings/installations/{installation-id}.

Você criou uma conexão com o GitHub Enterprise.

gcloud

Depois de instalar o app do GitHub, siga estas etapas para conectar o host do GitHub Enterprise por programação usando gcloud:

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 do arquivo para a chave privada gerada.

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

Em que:

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

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 é o nome da conexão.
- 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 do GitHub.
- APP_SLUG é o slug do app. Por exemplo, https://my-ghe-server.net/settings/apps/app-slug.
- PROJECT_ID é o ID do Google Cloud projeto.
- INSTALLATION_ID é o ID de instalação do 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 da AC.
```
  --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 Google Cloud projeto.
- 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 do arquivo para o certificado da AC.

Você criou uma conexão com o GitHub Enterprise.

Próximas etapas

Saiba como conectar um repositório ao GitHub Enterprise.
Saiba como realizar implantações azul-verde no Compute Engine.