Crie uma associação a um anfitrião do GitLab Enterprise Edition

Esta página explica como se ligar ao anfitrião do GitLab Enterprise Edition no Cloud Build.

Antes de começar

  • Enable the Cloud Build and Secret Manager APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

Requisitos do anfitrião

  • Se não tiver instalado uma instância do servidor do GitLab Enterprise Edition, consulte o guia de instalação do GitLab Enterprise Edition para obter instruções.

    Quando seguir as instruções para instalar uma instância do servidor do GitLab Enterprise Edition, tenha em atenção o seguinte:

    • Tem de configurar o seu anfitrião para processar o protocolo HTTPS. Os anfitriões configurados com o protocolo HTTP não são suportados.

    • Tem de configurar o anfitrião com o mesmo URL que é usado para aceder ao anfitrião a partir de Google Cloud. Para saber mais, consulte a documentação do GitLab sobre a configuração do URL externo.

Autorizações de IAM necessárias

Para associar o seu anfitrião do GitLab Enterprise Edition, conceda a função de administrador da ligação (roles/cloudbuild.connectionAdmin) do Cloud Build à 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.

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

Crie uma associação a um anfitrião do GitLab Enterprise Edition

Antes de criar uma associação de anfitrião para a sua instância do GitLab Enterprise Edition, tem de criar tokens de acesso pessoal no GitLab Enterprise Edition seguindo estes passos:

  1. Inicie sessão na sua instância do GitLab Enterprise Edition.

  2. Na página do GitLab Enterprise Edition da sua instância, clique no seu avatar no canto superior direito.

  3. Clique em Editar perfil.

  4. Na barra lateral esquerda, selecione Tokens de acesso.

    É apresentada a página Tokens de acesso pessoal.

  5. Crie um token de acesso com o âmbito api para usar na associação e desassociação de repositórios.

  6. Crie um token de acesso com o âmbito read_api para garantir que os repositórios do Cloud Build podem aceder ao código-fonte nos repositórios.

Consola

Para associar o seu anfitrião do GitLab Enterprise Edition 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. Na parte superior da página, selecione o separador 2.ª geração.

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

  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 GitLab 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 associação.

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

    1. Fornecedor do GitLab: selecione Edição Enterprise do GitLab autogerida como fornecedor.

    2. URL do anfitrião: introduza o URL do anfitrião para a sua ligação. Por exemplo, https://my-gle-server.net.

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

    4. 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 Google Cloud ID do projeto no menu pendente.

          • Região: este campo pré-seleciona a região da sua associaçã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. Na secção Tokens de acesso pessoal, introduza as seguintes informações:

    1. Token de acesso à API: introduza o token com o acesso ao âmbito api. Este token é usado para associar e desassociar repositórios.

    2. Ler chave de acesso à API: introduza a chave com o âmbito read_api acesso. Os acionadores do Cloud Build usam este token para aceder ao código-fonte nos repositórios.

  9. Clique em Ligar.

    Depois de clicar no botão Associar, os seus tokens de acesso pessoal são armazenados em segurança no Secret Manager. Após a ligação do anfitrião, o Cloud Build também cria um segredo de webhook em seu nome. Pode ver e gerir segredos na página Secret Manager. Pode ver e gerir os seus segredos na página Secret Manager.

Criou com êxito uma ligação do GitLab Enterprise Edition.

gcloud

Antes de associar o seu anfitrião do GitLab Enterprise Edition ao Cloud Build, conclua os passos seguintes para armazenar as suas credenciais:

  1. Armazene o seu token no Secret Manager.

  2. Crie um segredo de webhook no Secret Manager executando o seguinte comando:

     cat /proc/sys/kernel/random/uuid | tr -d '\n' | gcloud secrets create my-gle-webhook-secret --data-file=-

  3. Se armazenar os seus segredos num Google Cloud projeto diferente do que planeia usar para criar uma ligação de anfitrião, introduza o seguinte comando para conceder ao seu projeto acesso ao agente do serviço Cloud Build:

    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"

    Onde:

    • PROJECT_ID é o ID do seu Google Cloud projeto.

Já pode continuar a associar o seu anfitrião do GitLab Enterprise Edition ao Cloud Build.

Conclua os seguintes passos:

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

    gcloud builds connections create gitlab CONNECTION_NAME \
  --host-uri=HOST_URI \
  --project=PROJECT_ID \
  --region=REGION \
  --authorizer-token-secret-version=projects/PROJECT_ID/secrets/API_TOKEN/versions/SECRET_VERSION \
  --read-authorizer-token-secret-version=projects/PROJECT_ID/secrets/READ_TOKEN/versions/SECRET_VERSION \
  --webhook-secret-secret-version=projects/PROJECT_ID/secrets/WEBHOOK_SECRET/versions/SECRET_VERSION

    Onde:

    • CONNECTION_NAME é um nome para a sua ligação no Cloud Build.
    • HOST_URI é o URI da sua instância do GitLab Enterprise Edition. Por exemplo, https://my-gle-server.net.
    • PROJECT_ID é o ID do seu Google Cloud projeto.
    • REGION é a região da sua ligação.
    • API_TOKEN é o nome do seu token com o âmbito api.
    • READ_TOKEN é o nome do seu token com o âmbito read_api.
    • SECRET_VERSION é a versão do seu segredo.
    • WEBHOOK_SECRET é o seu código secreto do webhook.

Criou com êxito uma ligação do GitLab Enterprise Edition.

Terraform

Pode associar o seu anfitrião do GitLab Enterprise Edition ao Cloud Build através do Terraform. Saiba mais sobre o Terraform no Google Cloud.

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

  • Configura o fornecedor do Terraform para Google Cloud recursos
  • Cria um segredo para armazenar o seu token de acesso pessoal do GitLab Enterprise Edition
  • Concede as autorizações necessárias ao agente de serviço do Cloud Build para aceder a segredos

  • Cria uma ligação ao GitLab Enterprise Edition

    // Configure the Terraform Google provider
terraform {
  required_providers {
    google = {}
  }
}

// Create secrets and grant permissions to the Cloud Build service agent
resource "google_secret_manager_secret" "api-pat-secret" {
    project = "PROJECT_ID"
    secret_id = "GITLAB_PAT_API"

    replication {
        auto {}
     }
 }

 resource "google_secret_manager_secret_version" "api-pat-secret-version" {
     secret = google_secret_manager_secret.api-pat-secret.id
     secret_data = "GITLAB_API_TOKEN"
 }

 resource "google_secret_manager_secret" "read-pat-secret" {
     project = "PROJECT_ID"
     secret_id = "GITLAB_PAT_READ"

     replication {
         auto {}
     }
}

resource "google_secret_manager_secret_version" "read-pat-secret-version" {
    secret = google_secret_manager_secret.read-pat-secret.id
    secret_data = "GITLAB_API_TOKEN"
}

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-pak" {
  project = google_secret_manager_secret.api-pat-secret.project
  secret_id = google_secret_manager_secret.api-pat-secret.secret_id
  policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-rpak" {
  project = google_secret_manager_secret.read-pat-secret.project
  secret_id = google_secret_manager_secret.read-pat-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"

    gitlab_config {
        host_uri = "URI"
        authorizer_credential {
            user_token_secret_version = google_secret_manager_secret_version.api-pat-secret-version.id
        }
        read_authorizer_credential {
             user_token_secret_version = google_secret_manager_secret_version.read-pat-secret-version.id
        }
        webhook_secret_secret_version = google_secret_manager_secret_version.webhook-secret-secret-version.id
    }

    depends_on = [
        google_secret_manager_secret_iam_policy.policy-pak,
        google_secret_manager_secret_iam_policy.policy-rpak,
        google_secret_manager_secret_iam_policy.policy-whs
    ]
}

Substitua o seguinte:

  • PROJECT_ID: o ID do seu Google Cloud projeto.
  • GITLAB_PAT_API: o seu token de acesso pessoal com acesso api.
  • GITLAB_API_TOKEN: o seu token de acesso pessoal.
  • GITLAB_PAT_READ: a sua chave de acesso pessoal com acesso read_api.
  • WEBHOOK_SECRET: o nome do segredo que contém o valor secreto do webhook.
  • WEBHOOK_SECRET_VALUE: o valor do segredo do webhook.

  • PROJECT_NUMBER: o número do seu Google Cloud projeto. Pode encontrar o número do projeto na página Boas-vindas da Google Cloud consola ou executando o seguinte comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

  • REGION: a região da sua ligação.

  • CONNECTION_NAME: um nome para a ligação do anfitrião do GitLab Enterprise Edition no Cloud Build.

  • URI: o URI da sua associação, por exemplo, https://my-gitlab-enterprise-server.net.

Criou com êxito uma ligação do GitLab Enterprise Edition.

Rode tokens de acesso antigos ou expirados do GitLab Enterprise Edition

Se o token de acesso do GitLab Enterprise Edition expirar, a ligação do host do Cloud Build é desassociada do respetivo repositório do GitLab Enterprise Edition. Como resultado, vai ver erros nas seguintes circunstâncias:

  • Quando tenta associar um repositório do GitLab Enterprise Edition a uma ligação do Cloud Build, é apresentada uma mensagem Failed to fetch repositories to link. Check that Cloud Build is still authorized to access data from the selected connection.

  • Na página Acionadores, quando clica em Executar, a página Executar acionador é aberta e mostra uma mensagem Failed to list branches. You can still enter one manually.

Para rodar um token antigo ou expirado para a sua ligação, faça o seguinte:

  1. Encontre os segredos associados à ligação do anfitrião:

    1. Execute o seguinte comando:

      gcloud builds connections describe CONNECTION_PATH --region=REGION

      Onde:

      • CONNECTION_PATH é o caminho da ligação do anfitrião do GitLab Enterprise Edition no Cloud Build, no formato projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME.
      • REGION é a região da sua ligação.

    2. No resultado do comando, procure os valores dos campos do token de utilizador. readAuthorizerCredential.userTokenSecretVersion mostra o nome do Secret Manager do read_api token e authorizerCredential.userTokenSecretVersion mostra o nome do Secret Manager do api token. Estes nomes são armazenados como segredos no Secret Manager.

  2. Rode cada chave de acesso no GitLab Enterprise Edition:

    1. Aceda ao repositório do GitLab Enterprise Edition associado à ligação do anfitrião do Cloud Build.

    2. Siga as instruções na documentação do GitLab para rodar um token de acesso. Quando roda um token, o GitLab Enterprise Edition cria um novo token com novas credenciais e invalida a versão anterior desse token. O token com rotação tem as mesmas autorizações e âmbito que o token original.

    3. Copie o ID do token rodado.

  3. Crie uma nova versão do segredo para cada token:

    1. Abra a página Secret Manager na Google Cloud consola:

      Abra a página Secret Manager

    2. Para cada token que rodou, encontre o nome secreto que identificou no passo 1 e clique em Ações e, de seguida, clique em Adicionar nova versão.

    3. Na janela Adicionar nova versão, introduza o ID do token rodado e, de seguida, clique em Adicionar nova versão.

Para mais informações, consulte o artigo Validade do token de acesso na documentação do GitLab Enterprise Edition.

O que se segue?