Conecte-se ao Jenkins

É possível iniciar builds automáticos com gatilhos do Jenkins e webhooks do Secure Source Manager.

Funções exigidas

Para receber as permissões necessárias para criar gatilhos de build do Jenkins, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Administrador de repositórios do Secure Source Manager (roles/securesourcemanager.repoAdmin) no seu repositório
• Acessador de instâncias do Secure Source Manager (roles/securesourcemanager.instanceAccessor) na instância do Secure Source Manager

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para informações sobre como conceder papéis do Secure Source Manager, consulte Controle de acesso com o IAM e Conceder acesso à instância aos usuários.

Configurar um gatilho de webhook

O Jenkins usa plug-ins de gatilho de compilação para ativar a automação de CI/CD. Você pode configurar acionadores para detectar eventos de entrada, como quando uma nova confirmação é enviada para um repositório ou quando uma solicitação de envio é iniciada e, em seguida, executar um build automaticamente quando novos eventos chegam. Também é possível configurar acionadores para criar código em qualquer alteração no seu repositório de origem ou somente em alterações que corresponderem a determinados critérios.

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

1. Instale o plug-in Git, plug-in de credenciais SSH e plug-in de gatilho de webhook genérico no seu servidor Jenkins.

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

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

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

   Em que:

   • 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 Identificar projetos para saber onde encontrar o número do projeto.

   Por exemplo, o comando a seguir adiciona o domínio da instância para uma instância chamada prod-test-instance com um número de projeto de 123456789.

   ssh -t [e-mail]
   

   Responda yes para adicionar o domínio da instância à lista de hosts conhecidos.

4. Na página Gerenciar credenciais do Jenkins:

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

5. Clique em Criar.

6. Na interface da Web do Jenkins, crie um job.

7. Na página de configuração do job do Jenkins, na seção Gerenciamento de código-fonte, selecione Git.

8. Na seção Git, cole o URL SSH do repositório do Secure Source Manager como o URL do repositório, insira suas ramificações de build (por exemplo, */main) e selecione a credencial de chave SSH privada salva que você adicionou anteriormente na página Gerenciar credenciais.

9. Na seção Gatilhos de build, selecione Gatilho de webhook genérico.

   Se quiser, adicione um token para que o job seja acionado apenas se ele for fornecido durante a invocação. Para adicionar um token, na seção Acionador de webhook genérico, insira um token no campo Token.

10. Na seção Build, forneça um script de build que você quer para este job do Jenkins. Por exemplo, execute cat README.md para imprimir o conteúdo de README.md.

11. Clique em Salvar para criar o job do Jenkins.

Configurar uma conta de serviço e conceder as permissões necessárias

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

   Verifique se você tem a permissão iam.serviceAccounts.actAs na conta de serviço. Essa permissão faz parte do papel Usuário da conta de serviço (roles/iam.serviceAccountUser).

2. Na interface da 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 uma lista das chaves adicionadas é exibida.

4. Clique em Adicionar chave.

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

   1. Conta de serviço: o e-mail da conta de serviço que você quer usar com 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 em que a conta de serviço foi criada.

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

Conceder permissões ao agente de serviço do Secure Source Manager

Se a conta de serviço não estiver no mesmo projeto da sua instância do Secure Source Manager, conceda ao agente de serviço do Secure Source Manager o papel de criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) ou a permissão iam.serviceAccounts.signJwt.

Se a conta de serviço estiver no mesmo projeto da instância do Secure Source Manager, pule para Conceder à conta de serviço uma função de repositório.

1. Execute o seguinte comando para receber a política do IAM atual da 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 você quer usar. A conta precisa ser formatada como um ID numérico de conta de serviço ou como um e-mail, assim: 123456789876543212345 ou [e-mail].

   A saída inclui todas as vinculações atuais ou, se não houver nenhuma, o valor etag semelhante a este:

   {
   "etag": "BwUjHYKJUiQ="
   }
   

   Importante: mantenha o valor etag da resposta get-iam-policy para não substituir as mudanças de política de outra pessoa. Se quiser substituir todas as outras mudanças, remova o valor etag.

2. Copie a saída para um novo arquivo chamado policy.json.

3. Para conceder ao agente de serviço do Secure Source Manager o papel de criador de token 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 comando a seguir para substituir a política do IAM atual da conta de serviço:

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

   Substitua:

   • SERVICE_ACCOUNT pelo ID ou e-mail da conta de serviço.
   • POLICY_FILE com o local e o nome do arquivo formatado em JSON, incluindo a nova política.

Conceder um papel de repositório à conta de serviço

1. Na interface da Web do Secure Source Manager, navegue até o repositório em que você quer conceder permissões à conta de serviço.
2. Clique na guia Permissões.
3. Clique em Adicionar usuários.
4. No campo Adicionar principal, insira o endereço de e-mail da conta de serviço.
5. No menu suspenso Papel, selecione Leitor do repositório do Secure Source Manager.

6. Atribua à conta de serviço o papel securesourcemanager.instanceAccessor executando o seguinte comando:

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

   Substitua:

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

Configurar um webhook

1. Na interface da Web do Secure Source Manager, navegue até o repositório em que você quer criar um webhook.
2. Clique em Configurações.
3. Clique em Webhooks e em Adicionar webhook.

4. No campo ID do hook, insira um ID para o webhook.

   Observação: os IDs de hook precisam seguir a convenção de nomenclatura de recursos. Eles precisam incluir apenas letras minúsculas, números ou traços, começar com uma letra e não podem ser alterados depois da criação do webhook.

5. No campo URL de destino, insira o URL do gatilho do Jenkins.

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

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

   Por exemplo, se o URL for semelhante a este: 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 seção Acionar em, selecione uma das seguintes opções:

   • Push: para acionar um envio para o repositório.
   • Estado da solicitação de pull alterado: para acionar uma mudança no estado da solicitação de pull.

8. Se você selecionou Push, insira uma lista de permissão para eventos de envio no campo Filtro de ramificação.

   O campo Filtro de ramificação usa o padrão glob, e apenas operações nas ramificações correspondentes vão acionar um gatilho de compilação. Se o campo estiver vazio ou for *, os eventos de push de todas as ramificações serão informados.

9. Clique em Add webhook.

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

    Observação: ao adicionar ou editar um webhook, o comprimento do Sensitive Query String pode ser inconsistente com o inserido, o que é esperado, já que strings de substituição são usadas para garantir a segurança.

Testar seu webhook

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

2. Role até a parte de baixo da página e clique em Testar entrega.

   Um evento falso é adicionado à fila de entrega. Pode levar alguns segundos para que ele apareça no histórico de entregas.

3. Também é possível usar um comando git para enviar ou mesclar uma solicitação de envio e testar o webhook.

4. No projeto do Jenkins, confira o build acionado pelo evento de teste em Histórico de builds.

5. Você também pode conferir a Solicitação e a Resposta da entrega do teste na seção Entregas recentes da página do webhook do Secure Source Manager depois de enviar sua primeira entrega de teste.

A seguir

• Consulte a documentação do Jenkins.