Tutorial: configurar um executor do Buildkite hospedado pelo CodeBuild

Como gerar um token de agente do Buildkite

1. No cluster do Buildkite, escolha Tokens de agente e Novo token.

2. Adicione uma descrição ao token e clique em Criar token.

3. Salve o valor do token do agente, pois ele será usado posteriormente durante a configuração do projeto do CodeBuild.

   

Para criar um projeto do CodeBuild com um webhook

1. Abra o console do AWS CodeBuild em https://console.aws.amazon.com/codesuite/codebuild/home.

2. Crie um projeto de compilação auto-hospedado. Para obter informações, consulte Criar um projeto de compilação (console) e Executar uma compilação (console).

   • Em Configuração do projeto, selecione Projeto de executor. Em Executor:

     • Em Provedor de executor, escolha Buildkite.

     • Em Token de agente do Buildkite, escolha Criar um token de agente usando a página de criação secreta. Será exibida uma solicitação para criar um segredo no AWS Secrets Manager com um valor de segredo igual ao token do agente do Buildkite que você gerou acima.

     • (Opcional) Se você quiser usar as credenciais gerenciadas do CodeBuild para seu trabalho, selecione o provedor do repositório de origem correspondente nas Opções de credenciais de origem do Buildkite e verifique se as credenciais estão configuradas para sua conta. Além disso, verifique se o pipeline do Buildkite usa o Checkout via HTTPS.

     nota

     O Buildkite requer credenciais de origem no ambiente de compilação para extrair a origem do trabalho. Consulte as opções de credenciais de origem disponíveis em Autenticar o Buildkite em um repositório privado.

   • (Opcional) Em Ambiente:

     • Escolha uma Imagem de ambiente e Computação compatíveis.

       Observe que você tem a opção de substituir as configurações de imagem e instância usando um rótulo nas etapas de YAML do Buildkite. Para obter mais informações, consulte Etapa 4: atualizar as etapas do pipeline do Buildkite.

   • (Opcional) Em Buildspec:

     • O buildspec será ignorado por padrão, a menos que buildspec-override: "true" seja adicionado como rótulo. Em vez disso, o CodeBuild o substituirá para usar comandos que configurarão o executor auto-hospedado.

       nota

       O CodeBuild não é compatível com arquivos buildspec para compilações de executores auto-hospedados. Para buildspecs em linha, será necessário habilitar git-credential-helper no buildspec se você tiver configurado as credenciais de origem gerenciada do CodeBuild

3. Continue com os valores padrão e escolha Criar projeto de compilação.

4. Salve o URL da carga útil e os valores de Segredo no pop-up Criar webhook. Siga as instruções no pop-up para criar um webhook da organização do Buildkite ou continue para a próxima seção.

Como criar um webhook no Buildkite

1. Acesse a página de Configurações da organização do Buildkite.

2. Em Integrações, selecione Serviços de notificação.

3. Escolha Adicionar ao lado da caixa Webhook. Na página Adicionar notificação de webhook, use a seguinte configuração:

   1. Em URL do webhook, adicione o valor salvo de URL de carga útil.

   2. Em Token, verifique se a opção Enviar o token como X-Buildkite-Token está selecionada. Adicione o valor de Segredo do webhook ao campo Token.

   3. Em Token, verifique se a opção Enviar o token como X-Buildkite-Token está selecionada. Adicione o valor de Segredo do webhook ao campo Token.

   4. Em Eventos, selecione o evento job.scheduled do webhook.

   5. (Opcional) Em Pipelines, você pode optar por acionar somente compilações para um pipeline específico.

4. Escolha Adicionar notificação de webhook.

Atualizar as etapas do pipeline

1. Acesse a página de etapas do pipeline do Buildkite selecionando o pipeline do Buildkite, escolhendo Configurações e Etapas.

   Se ainda não tiver feito isso, escolha Converter em etapas do YAML.

   

2. No mínimo, você precisará especificar uma Tag de agente do Buildkite referenciando o nome do pipeline do CodeBuild. O nome do projeto é necessário para vincular as configurações relacionadas à AWS do trabalho do Buildkite a um projeto específico do CodeBuild. Ao incluir o nome do projeto no YAML, o CodeBuild pode invocar trabalhos com as configurações corretas do projeto.

   agents:
     project: "codebuild-<project name>"

   Veja a seguir um exemplo de etapas do pipeline do Buildkite com apenas a tag do rótulo do projeto:

   agents:
     project: "codebuild-myProject"
   steps:
     - command: "echo \"Hello World\""

   Você também pode substituir a imagem e o tipo de computação no rótulo. Para obter uma lista das imagens disponíveis, consulte Imagens de computação compatíveis com o executor do Buildkite hospedado pelo CodeBuild. O tipo de computação e a imagem no rótulo substituirão as configurações do ambiente no projeto. Para substituir as configurações de ambiente por uma compilação de computação do CodeBuild EC2 ou Lambda, use a seguinte sintaxe:

   agents:
     project: "codebuild-<project name>"
     image: "<environment-type>-<image-identifier>"
     instance-size: "<instance-size>"

   Veja a seguir um exemplo de etapas do pipeline do Buildkite com substituições de imagens e tamanhos de instância:

   agents:
     project: "codebuild-myProject"
     image: "arm-3.0"
     instance-size: "small"
   steps:
     - command: "echo \"Hello World\""

   Você pode substituir a frota usada para a compilação no rótulo. Isso substituirá as configurações de frota definidas no projeto para usar a frota especificada. Consulte mais informações em Executar compilações em frotas de capacidade reservada.

   Para substituir as configurações da frota para uma compilação computacional do Amazon EC2, use a seguinte sintaxe:

   agents:
     project: "codebuild-<project name>"
     fleet: "<fleet-name>"
   

   Para substituir a frota e a imagem usadas para a compilação, use a seguinte sintaxe:

   agents:
     project: "codebuild-<project name>"
     fleet: "<fleet-name>"
     image: "<environment-type>-<image-identifier>"

   Veja a seguir um exemplo de etapas do pipeline do Buildkite com substituições de frota e imagem:

   agents:
     project: "codebuild-myProject"
     fleet: "myFleet"
     image: "arm-3.0"
   steps:
     - command: "echo \"Hello World\""

3. Você pode optar por executar comandos de buildspec em linha durante a compilação do executor do Buildkite auto-hospedado (consulte mais detalhes em Executar os comandos de buildspec nas fases INSTALL, PRE_BUILD e POST_BUILD). Para especificar que a compilação do CodeBuild deve executar comandos de buildspec durante a compilação do executor auto-hospedado do Buildkite, use a seguinte sintaxe:

   agents:
     project: "codebuild-<project name>"
     buildspec-override: "true"

   Veja a seguir um exemplo de um pipeline do Buildkite com uma substituição de buildspec:

   agents:
     project: "codebuild-myProject"
     buildspec-override: "true"
   steps:
     - command: "echo \"Hello World\""

4. Como opção, você pode fornecer rótulos além daqueles com que o CodeBuild é compatível. Esses rótulos serão ignorados com o objetivo de substituir os atributos da compilação, mas não falharão na solicitação do webhook. Por exemplo, adicionar myLabel: “testLabel" como rótulo não impedirá a execução da compilação.

Como fazer a autenticação com o CodeBuild

O CodeBuild oferece processamento de credenciais gerenciado para os tipos de origens compatíveis. Para usar as credenciais de origem do CodeBuild a fim de extrair o repositório de origem do trabalho, você pode seguir estas etapas:

1. No console do CodeBuild, acesse Editar projeto ou crie um projeto do CodeBuild usando as etapas em Etapa 2: criar um projeto do CodeBuild com um webhook.

2. Em Opções de credencial de origem do Buildkite, selecione o provedor do repositório de origem do trabalho.

   1. Se você quiser usar as credenciais do CodeBuild no nível da conta, verifique se elas estão configuradas corretamente. Além disso, se o projeto tiver um buildspec em linha configurado, verifique se o git-credential-helper está habilitado.

   2. Se você quiser usar as credenciais do CodeBuild no nível do projeto, selecione Usar credenciais de substituição somente para este projeto e configure as credenciais para o projeto.

3. Nas configurações do pipeline do Buildkite, acesse Configurações do repositório. Defina as configurações de checkout do repositório de origem como Checkout via HTTPS

   

Como fazer a autenticação com os segredos do Buildkite

O Buildkite mantém um plug-in de ssh-checkout que pode ser usado para autenticar o executor auto-hospedado em um repositório de origem externo usando uma chave SSH. O valor da chave é armazenado como um segredo do Buildkite e obtido automaticamente pelo agente de executor auto-hospedado do Buildkite ao tentar extrair um repositório privado. Para configurar o plug-in ssh-checkout do pipeline do Buildkite, siga estas etapas:

1. Gere uma chave SSH pública e privada usando o endereço de e-mail, por exemplo ssh-keygen -t rsa -b 4096 -C "myEmail@address.com"

2. Adicione a chave pública ao repositório de origem privado. Por exemplo, você pode seguir este guia para adicionar uma chave a uma conta do GitHub.

3. Adicione um novo segredo de chave SSH ao cluster do Buildkite. No cluster do Buildkite, selecione Segredos → Novo segredo. Adicione um nome para o segredo no campo Chave e adicione a chave SSH privada no campo Valor:

   

4. No pipeline do Buildkite, acesse as configurações do repositório e defina o checkout para usar SSH.

   

5. Atualize as etapas do YAML do pipeline para usar o plug-in git-ssh-checkout. Por exemplo, o arquivo YAML do pipeline a seguir usa a ação de checkout com a chave secreta do Buildkite acima:

   agents:
     project: "codebuild-myProject"
   steps:
     - command: "npm run build"
       plugins:
         - git-ssh-checkout#v0.4.1:
             ssh-secret-key-name: 'SOURCE_SSH_KEY'

6. Ao executar um trabalho de execução auto-hospedado do Buildkite no CodeBuild, o Buildkite agora usa automaticamente o valor do segredo configurado ao extrair o repositório privado