Associe ao Jenkins

Pode iniciar compilações automáticas com acionadores do Jenkins e webhooks do Secure Source Manager.

Funções necessárias

Para receber as autorizações de que precisa para criar acionadores de compilação do Jenkins, peça ao seu administrador que lhe conceda as seguintes funções do IAM:

• Secure Source Manager Repo Admin (roles/securesourcemanager.repoAdmin) no seu repositório
• Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) na instância do Secure Source Manager

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Para obter informações sobre a concessão de funções do Secure Source Manager, consulte os artigos Controlo de acesso com o IAM e Conceda aos utilizadores acesso à instância.

Configure um acionador de webhook

O Jenkins usa plug-ins de acionadores de compilação para ativar a automatização de CI/CD. Pode configurar acionadores para ouvir eventos recebidos, como quando um novo commit é enviado para um repositório ou quando é iniciada uma solicitação de obtenção, e, em seguida, executar automaticamente uma compilação quando chegarem novos eventos. Também pode configurar acionadores para criar código em quaisquer alterações ao repositório de origem ou apenas em alterações que correspondam a determinados critérios.

Para configurar um acionador de webhook genérico do Jenkins:

1. Instale o Git Plugin, o SSH Credential Plugin e o Generic Webhook Trigger Plugin do Jenkins no seu servidor do Jenkins.

2. Gere um par de chaves SSH válido no seu servidor Jenkins. O Secure Source Manager só suporta chaves do tipo RSA.

3. Adicione o domínio da instância do Secure Source Manager ao ficheiro known_hosts SSH do servidor Jenkins executando o seguinte comando:

   ssh -t git@INSTANCE_ID-INSTANCE_PROJECT_NUMBER-ssh.us-central1.sourcemanager.dev
   

   Onde:

   • INSTANCE_ID é o nome da sua instância do Secure Source Manager.
   • INSTANCE_PROJECT_NUMBER é o número do projeto da sua instância do Secure Source Manager. Consulte o artigo Identificar projetos para ver informações sobre onde encontrar o número do projeto.

   Por exemplo, o comando seguinte adiciona o domínio da instância para uma instância com o nome prod-test-instance e o número do projeto 123456789.

   ssh -t [e-mail]
   

   Responder yes para adicionar o domínio da instância à lista de anfitriões conhecidos.

4. Na página Manage Credentials do Jenkins:

   1. Selecione Nome de utilizador SSH com chave privada.
   2. Cole a chave privada de SSH do servidor Jenkins.
   3. No menu pendente Tipo, preencha os outros campos conforme necessário.

5. Clique em Criar.

6. Na interface Web do Jenkins, crie uma nova tarefa do Jenkins.

7. Na página de configuração da tarefa do Jenkins, na secção Source Code Management, selecione Git.

8. Na secção Git, cole o URL SSH do repositório do Secure Source Manager como URL do repositório, introduza os ramos de compilação (por exemplo, */main) e, em seguida, selecione a credencial de chave SSH privada guardada que adicionou anteriormente na página Gerir credenciais.

9. Na secção Criar acionadores, selecione Acionador de webhook genérico.

   Opcionalmente, pode adicionar um token para que a tarefa só seja acionada se esse token for fornecido durante a invocação. Para adicionar um token, na secção Acionador de webhook genérico, pode introduzir um token no campo Token.

10. Na secção Compilação, indique um script de compilação que quer ter para esta tarefa do Jenkins. Por exemplo, pode executar cat README.md para imprimir o conteúdo de README.md.

11. Clique em Guardar para criar a tarefa do Jenkins.

Configure uma conta de serviço e conceda as autorizações necessárias

1. Se ainda não tiver uma conta de serviço que queira usar, crie uma conta de serviço.

   Certifique-se de que tem a autorização iam.serviceAccounts.actAs na conta de serviço. Esta autorização faz parte da função de utilizador da conta de serviço (roles/iam.serviceAccountUser).

2. Na interface Web do Secure Source Manager, clique no menu mais opções.

3. Clique em Chaves SSH da conta de serviço. A página Chaves SSH da conta de serviço é aberta e é apresentada uma lista de todas as chaves existentes que adicionou.

4. Clique em Adicionar chave.

5. Na página Adicionar chave SSH, introduza os seguintes valores para a sua chave:

   1. Conta de serviço: o email da conta de serviço para a conta de serviço com a qual quer usar a chave SSH no formato SA_NAME@PROJECT_ID.iam.gserviceaccount.com

      Onde

      • SA_NAME é o nome da conta de serviço.
      • PROJECT_ID é o ID do projeto no qual a conta de serviço foi criada.

   2. Chave pública de SSH: a sua chave pública de SSH do Jenkins.

Conceda autorizações ao agente de serviço do Secure Source Manager

Se a conta de serviço não estiver no mesmo projeto que a sua instância do Secure Source Manager, também tem de conceder ao agente de serviço do Secure Source Manager a função de criador de tokens de conta de serviço (roles/iam.serviceAccountTokenCreator) ou a autorização iam.serviceAccounts.signJwt.

Se a sua conta de serviço estiver no mesmo projeto que a sua instância do Secure Source Manager, avance para a secção Conceda à conta de serviço uma função de repositório.

1. Execute o seguinte comando para obter a política de IAM existente para a sua conta de serviço:

   gcloud iam service-accounts get-iam-policy SERVICE_ACCOUNT \
       --format json
   

   Em que SERVICE_ACCOUNT é a conta de serviço que quer usar. A conta deve ser formatada como um ID numérico da conta de serviço ou como um email, da seguinte forma: 123456789876543212345 ou [e-mail].

   A saída inclui todas as associações existentes ou, se não existirem, o valor etag semelhante ao seguinte:

   {
   "etag": "BwUjHYKJUiQ="
   }
   

   Importante: mantenha o valor etag da resposta para garantir que não substitui as alterações de política de outra pessoa.get-iam-policy Se quiser substituir todas as outras alterações, pode remover o valor etag.

2. Copie o resultado para um novo ficheiro com o nome policy.json.

3. Para conceder ao agente do serviço Secure Source Manager a função de criador de tokens da conta de serviço (roles/iam.ServiceAccountTokenCreator), modifique o policy.json para adicionar o seguinte:

   {
       "role": "roles/iam.serviceAccountTokenCreator",
       "members": [
           "serviceAccount:[e-mail]"
       ]
   }
   

   Em que INSTANCE_PROJECT_NUMBER é o número do projeto da sua instância do Secure Source Manager.

4. Execute o seguinte comando para substituir a política de IAM existente da conta de serviço:

   gcloud iam service-accounts set-iam-policy SERVICE_ACCOUNT POLICY_FILE
   

   Substitua o seguinte:

   • SERVICE_ACCOUNT com o ID ou o email da conta de serviço.
   • POLICY_FILE com a localização e o nome do ficheiro formatado em JSON, incluindo a nova política.

Conceda à conta de serviço uma função de repositório

1. Na interface Web do Secure Source Manager, navegue para o repositório no qual quer conceder autorizações à conta de serviço.
2. Clique no separador Autorizações.
3. Clique em Adicionar utilizadores.
4. No campo Adicionar principal, introduza o endereço de email da conta de serviço.
5. No menu pendente Função, selecione Leitor do repositório do Secure Source Manager.

6. Atribua à conta de serviço a função securesourcemanager.instanceAccessor executando o seguinte comando:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:SA_EMAIL \
       --role=roles/securesourcemanager.instanceAccessor
   

   Substitua o seguinte:

   • PROJECT_ID com o ID do projeto da instância do Secure Source Manager.
   • SA_EMAIL com o email da conta de serviço.

Configure um webhook

1. Na interface Web do Secure Source Manager, navegue para o repositório para o qual quer criar um webhook.
2. Clique em Definições.
3. Clique em Webhooks e, de seguida, em Adicionar webhook.

4. No campo ID do comando, introduza um ID para o webhook.

   Nota: os IDs dos hooks têm de seguir a convenção de nomenclatura de recursos. Têm de incluir apenas letras minúsculas, números ou traços, têm de começar por uma letra e não podem ser alterados após a criação do webhook.

5. No campo URL de destino, introduza o URL do acionador do Jenkins.

6. Se usou o token opcional ao configurar o acionador do Jenkins, o URL do acionador do Jenkins vai conter esse token no final. Para evitar a fuga do token, remova-o do final do URL de destino e copie-o para o campo String de consulta sensível.

   Para localizar o token no URL do acionador, procure o texto que começa com token=

   Por exemplo, se o seu URL for semelhante ao seguinte: https://jenkins-server.com/generic-webhook-trigger/invoke?token=jenkins-job1

   Copie e remova a parte que começa com o ponto de interrogação ?token=jenkins-job1 do campo URL de destino. Em seguida, remova o ponto de interrogação inicial e mova a parte restante token=jenkins-job1 para o campo String de consulta sensível.

7. Na secção Acionar em, selecione uma das seguintes opções:

   • Push: para acionar quando é enviado um push para o repositório.
   • Pull request state changed: para acionar uma alteração no estado do pedido de envio.

8. Se selecionou Push, pode introduzir uma lista de autorizações para eventos push no campo Filtro de ramificação.

   O campo Filtro de ramificação usa o padrão glob e apenas as operações nas ramificações correspondentes acionam uma compilação. Se o campo estiver vazio ou for *, são comunicados eventos push para todas as ramificações.

9. Clique em Adicionar webhook.

10. O webhook é apresentado na página Webhooks.

    Nota: quando adiciona ou edita um webhook, o comprimento do Sensitive Query String pode ser inconsistente com o introduzido, o que é esperado, uma vez que as strings de marcadores de posição são usadas para garantir a segurança.

Teste o webhook

1. Na página Webhooks do Secure Source Manager, clique no webhook que quer testar.

2. Aceda à parte inferior da página e clique em Testar entrega.

   Um evento falso é adicionado à fila de entrega. Pode demorar alguns segundos até aparecer no histórico de entregas.

3. Também pode usar um comando git para enviar ou unir um pedido de obtenção para testar o webhook.

4. No projeto Jenkins, veja a compilação acionada pelo evento de teste no Histórico de compilações.

5. Também pode ver o Pedido e a Resposta ao envio de teste na secção Envios recentes da página do webhook do Gestor de origens seguras depois de enviar o seu primeiro envio de teste.

O que se segue?

• Explore a documentação do Jenkins.