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 concluir instruções nesta página.

Permissões do IAM obrigatórias

Para conectar seu host do GitHub Enterprise, conceda ao 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 da gcloud, conceda o papel de administrador do Secret Manager (roles/secretmanager.admin) ao agente de serviço do Cloud Build executando o comando abaixo no seu projeto do 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 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, escolha 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 esquerdo, selecione GitHub Enterprise como seu provedor de origem.
Na seção Configurar conexão, digite as seguintes informações:
1. Região: selecione uma região para sua 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 CA: clique em "Procurar" para fazer o 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 à 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 o seguintes informações:
      - Projeto: insira ou selecione o ID do projeto do Google Cloud no menu suspenso.
      - Região: este 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 seu 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 seu 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 o secret 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 de 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 acessar o secret, consulte Listar secrets e ver detalhes do secret.

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

Você criou uma conexão do 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 privada, especifique seu recurso do diretório de serviços. Também é possível especificar seu 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 no 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 do arquivo 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.
Acesse o link retornado na etapa anterior para criar e instalar o App GitHub do Cloud Build no servidor da empresa.
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 conexão.
Se o campo installationState estiver definido como COMPLETE, significa que você instalou a conexão. Caso contrário, o campo installationState fornecerá 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 seu host do GitHub Enterprise de maneira programática ao Cloud Build, faça o seguinte: você precisa instalar o app GitHub concluindo as seguintes 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 da 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, conclua as seguintes 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 Inscrever-se em 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 Any account 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, a página do aplicativo será aberta. 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 esquerdo, 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 a seguir, 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 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 no Google Cloud.
PRIVATE_KEY_SECRET é o secret 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 conexão do GitHub.
URI é o URI da conexão. Por exemplo, https://my-github-enterprise-server.net.
APP_ID é o ID do 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 do GitHub. Seu o ID de instalação pode ser encontrado no URL do Cloud Build App GitHub, https://github.com/settings/installations/{installation-id}.

Você criou uma conexão do GitHub Enterprise.

gcloud

Depois de instalar o app GitHub, conclua as etapas a seguir para conecte seu host do GitHub Enterprise de maneira programática 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 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 no Google Cloud.
CLOUD_BUILD_SERVICE_AGENT é sua 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 instância do GitHub Enterprise. Por exemplo, https://mmy-ghe-server.net.
- APP_ID é o ID do 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 projeto no Google Cloud.
- INSTALLATION_ID é o ID de instalação do app do GitHub. Por exemplo: https://my-ghe-server.net/settings/installations/installation-id
- REGION é a região da sua conexão.
Se sua instância do GitHub Enterprise estiver em uma rede privada, especifique o 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 projeto no Google Cloud.
- REGION é a região da 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 de CA.

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.