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 and Secret Manager.
Ative as 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 as instruções nesta página.

Permissões do IAM obrigatórias

Para conectar o 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 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 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 privada, consulte Criar repositórios do GitHub Enterprise em uma rede privada para saber mais sobre os outros papéis do IAM necessários 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, siga estas etapas:

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

Abrir a página Repositórios

Você verá 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 2nd gen.
Clique em Criar conexão de host para conectar um novo host ao Cloud Build.
No painel esquerdo, 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 sua conexão.
  
  Observação :é preciso especificar uma região. Sua conexão não pode existir globalmente.
2. Nome: digite um nome para sua conexão.
Na seção Host details, digite as seguintes informações:
1. Host URL: insira o URL do host da sua conexão. Por exemplo, github.example.com
2. Certificado de CA: clique em "Procurar" para fazer upload do certificado autoassinado.
  
  Observação :seu 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 vai ser usado.
3. Em Tipo de conexão, selecione uma das seguintes opções:
  1. Internet pública: selecione essa opção se a instância puder ser acessada pela Internet pública.
  2. Acesso à rede privada: selecione essa opção caso sua instância esteja hospedada em uma rede privada.
  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: digite ou selecione o ID do projeto do Google Cloud no menu suspenso.
      - Region: esse campo seleciona previamente a região da conexão. A região especificada para seu serviço precisa corresponder à região associada à sua 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, será solicitado que você crie um app do GitHub no host do GitHub Enterprise e instale o app 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.

O Cloud Build armazena os dados de autenticação do app do GitHub criado como secrets no Secret Manager do 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 empresarial. O secret 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 acessar seu secret. Para ver o secret, consulte Listar secrets e ver 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 do GitHub Enterprise.

gcloud

Para conectar seu 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 instância do GitHub Enterprise. Por exemplo, https://mmy-ghe-server.net.
- REGION é a região da conexão.
Se a instância do GitHub Enterprise estiver em uma rede privada, especifique o 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 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 seu certificado de CA.
Depois de executar o comando gcloud builds connections..., você receberá um link para instalar o app GitHub do Cloud Build.
Siga o link retornado na etapa anterior para criar e instalar o app GitHub do Cloud Build no 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 conexão.
Se o campo installationState estiver definido como COMPLETE, a conexão foi instalada. Caso contrário, o campo installationState fornecerá um link para outras etapas necessárias.

Você criou uma conexão do GitHub Enterprise.

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

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

Registre um novo app GitHub. Por exemplo, você pode registrar um novo app GitHub em https://my-ghe-server.net/settings/apps/new.
Preencha os campos que aparecem na página:
1. GitHub App Name: digite 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 os tokens de autorização do usuário.
4. Na seção Webhook, siga estas etapas:
  - Ativo: marque a caixa para ativar seu webook.
  - Webhook URL: 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.
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 caixas a seguir:
  - Conferir execução
  - Pacote de verificações
  - Comentário de confirmação
  - Comentário do problema
  - Solicitação de envio
  - Comentário de análise da solicitação de envio
  - Enviar
  - Repositório
7. Marque a caixa Qualquer conta para permitir que seu app GitHub seja instalado por qualquer usuário ou organização.
Clique em Criar app GitHub para criar seu app GitHub.

Ao clicar em Create GitHub app, a página do seu app é 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 transferido por download 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 o app 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, conclua as etapas a seguir para conectar o host do GitHub Enterprise de maneira programática usando o Terraform ou o gcloud.

Terraform

Depois de instalar o app GitHub, é possível conectar o host do GitHub Enterprise ao Cloud Build usando o provedor do Google Terraform.

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

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

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 {
        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
    ]
}

Em que:

PROJECT_ID é o ID do projeto no Google Cloud.
PRIVATE_KEY_SECRET é o secret que contém a chave privada do app 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 conexão.
CONNECTION_NAME é o nome da sua conexão do GitHub.
URI é o URI da 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 do GitHub. O ID de instalação pode ser encontrado no URL do app GitHub para Cloud Build, https://github.com/settings/installations/{installation-id}.

Você criou uma conexão do GitHub Enterprise.

gcloud

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

Armazene os 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 que você criou para o secret do webhook.
PRIVATE_KEY_FILE é o caminho do arquivo para a chave privada que você gerou;

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 por projeto.

Crie sua conexão com o 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 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 no Google Cloud.
- INSTALLATION_ID é o ID de instalação do seu app do GitHub. Por exemplo, https://my-ghe-server.net/settings/installations/installation-id.
- REGION é a região da conexão.
Se a instância do GitHub Enterprise estiver em uma rede privada, especifique o 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 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 seu certificado de CA.

Você criou uma conexão do GitHub Enterprise.

Próximas etapas

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