Implantações do GitHub (visualização) com o Google Cloud Platform: um guia essencial

Motivação e Introdução

Pré-visualizações de construção não são nada de novo ou inovador. Heroku os teve por anos. No entanto, se você estiver criando no Google Cloud Platform, as coisas serão um pouco mais difíceis. O Google Cloud Build pode ser usado para implantar no Cloud Functions, Cloud Run, Kubernetes, App Engine etc. etc. Isso é o que torna as visualizações um pouco complicadas, pois o Cloud Build não sabe onde você está implantando seu aplicativo ou serviço. Eles têm um aplicativo GitHub para conectar os repositórios e mostrar o status da compilação no GitHub, mas é isso. Sem pré-visualizações, comentários ou qualquer coisa "normal" a que estamos acostumados em produtos como Heroku, Vercel ou Fly.

Há uma maneira "fácil" de postar um comentário em uma solicitação pull do GitHub do Cloud Build com uma solicitação HTTP simples. Mas por que é fácil quando você pode usar a API de implantação do GitHub .

Com esta API, você pode criar ambientes, ter diferentes variáveis por ambiente e mostrar o status de construção e implantação diretamente em uma solicitação pull. E assim que a implantação for concluída em sua plataforma de CD, você poderá adicionar a URL ao status da implantação. Isso é o que vamos fazer neste artigo.

Status de implantação do GitHub

Novamente, há outra maneira de fazer isso usando a API de implantações diretamente com solicitações HTTP. Às vezes, isso pode ser complicado e você precisará definir um token de acesso pessoal para autenticar com o GitHub. Em vez disso, decidimos montar um pequeno serviço Node.js que usa GitHub Apps para gerar um token de aplicativo e interagir com a API de implantações. Isso permite um controle um pouco mais preciso sobre o processo de implantação.

Isenção de responsabilidade

Este artigo foi escrito exclusivamente para Google Cloud Platform e GitHub. A compreensão básica das permissões do Google Cloud Platform, Google Cloud Build e IAM é assumida.

Você deve ter um projeto do Google Cloud Platform configurado.

GitHub Deployer (Node.js e Docker)

O GitHub Deployer é um pequeno serviço Node.js autorizado com um aplicativo GitHub e interage com a API GitHub Deployments. Os comandos são predefinidos e algumas informações precisam ser incorporadas à imagem do Docker, caso contrário, a configuração do tempo de execução no Cloud Build ficaria muito complexa.

A imagem do Docker não está pronta; você precisará construí-lo sozinho e enviá-lo para o seu registro. O melhor lugar é o Google Artifact Registry, onde as imagens do seu aplicativo também são armazenadas (o Container Registry está obsoleto):

1. Se ainda não tiver feito isso, crie um repositório do Artifact Registry

   
   

2. Crie um aplicativo GitHub e instale-o em sua organização

   • Criar um aplicativo GitHub

   • Permissões necessárias: 'pull_requests', 'implantações', 'metadados'

     
     

3. Copie o ID do aplicativo (na tela Configurações do aplicativo) e o ID de instalação do aplicativo (depois de clicar em "Configurar", você encontrará o ID de instalação no URL. Não faço ideia de onde mais isso pode ser encontrado)

   
   

4. Crie e baixe uma chave privada e converta-a em base64 ( base64 -i your.private-key.pem )

Crie a imagem do Docker

Fonte

O Cloud Build é executado em amd64 , portanto, precisamos buildx para criar a imagem para a plataforma x86:

docker buildx build --platform linux/amd64 . -t us-central1-docker.pkg.dev/[PROJECT]/docker/gh-deployer \

--build-arg GH_APP_ID=[GITHUB_APP_ID] \

--build-arg GH_APP_PRIVATE_KEY=[GITHUB_PRIVATE_KEY_BASE_64] \

--build-arg GH_APP_INSTALLATION_ID=[GITHUB_INSTALLATION_ID] \

--build-arg GH_OWNER=[GITHUB_ORG]

Empurre a imagem para o seu registro:

docker push us-central1-docker.pkg.dev/[PROJECT]/docker/gh-deployer

Execute a imagem do Docker localmente

docker run -it -e REPO_NAME=test -e REF=main -e ENVIRONMENT=test us-central1-docker.pkg.dev/[PROJECT]/docker/gh-deployer:latest create

Variáveis de ambiente necessárias:

• REPO_NAME : necessário o nome do repositório (por exemplo, gh-deployer )
• REF : necessário o branch, tag ou SHA para implantar (por exemplo, main )
• ENVIRONMENT : necessário o ambiente para implantar (por exemplo, preview )
• TRANSIENT_ENVIRONMENT : opcional/falso se definido como true , a implantação será excluída após um certo tempo
• DESCRIPTION : opcional uma descrição da implantação

Os seguintes comandos estão disponíveis como primeiro argumento:

• create - criar uma nova implantação
• pending - a compilação está pendente
• in_progress - a compilação está em andamento
• queued - a compilação está na fila
• success - a implantação foi bem-sucedida
• error - algo deu errado
• failure - a implantação falhou

Com o Cloud Build, as opções são atualmente um pouco limitadas. Não há estado pending , pois o Cloud Build precisa ser iniciado para criar a implantação inicial. queued também não faz muito sentido, portanto, em nossa própria configuração, estamos usando o seguinte:

1. gh-deployer/create para criar a implantação transitória para um commit
2. pgh-deployer/ending diretamente após a criação
3. Execute o kaniko build para criar a imagem do Docker para implantação
4. gh-deployer/in_progress após a conclusão da compilação e antes da implantação da imagem
5. gh-deployer/success após a implantação da imagem

Novamente, com o Cloud Build não sabemos onde será a implantação, portanto, há duas maneiras de passar a URL de implantação para a etapa success :

1. Em uma etapa de compilação, escreva a URL em /workspace/deployer_environment_url
2. Passe um segundo argumento para a imagem do Docker após success

Usamos o Cloud Run para nossas implantações, então aqui está a etapa de compilação para recuperar o URL de implantação para um determinado número de solicitação pull:

- nome: gcr.io/google.com/cloudsdktool/cloud-sdk

 env: - PR_NUMBER=$_PR_NUMBER script: >- gcloud run services list --project [project] --filter preview-$PR_NUMBER --format "value(status.address.url)" > /workspace/deployer_environment_url

Configuração do Cloud Build/Terraform

cloudbuild.yaml

cloudbuild.yaml

Aqui está um exemplo completo usando o arquivo de configuração cloudbuild.yaml . Usamos Kaniko para criar e Cloud Run como destino de implantação.

Se você trabalha com Terraform, também há um arquivo Terraform disponível: preview.tf

Ações do GitHub

Ao usar a API de implantações, você pode acionar GitHub Actions em deployment_status . Isso facilita a execução de verificações de garantia de qualidade, testes de ponta a ponta etc. em cada compilação de visualização. Aqui está um exemplo para executar o Playwright em cada visualização usando o environment_url que é passado para o estado success :

dramaturgo-qa:

 if: ${{ github.event.deployment\_status.state == 'success' }} timeout-minutes: 60 runs-on: ubuntu\-latest steps: \- uses: actions/[\[email protected\]](/cdn-cgi/l/email-protection) \- uses: actions/setup\-[\[email protected\]](/cdn-cgi/l/email-protection) with: node-version: 20 cache: 'npm' \- run: npm ci \- name: Install Playwright Browsers run: npm exec playwright install \-\-with\-deps \-y \- name: Run Playwright tests run: pnpm exec playwright test env: BASE\_URL: ${{github.event.deployment\_status.environment\_url}} \- uses: actions/upload\-[\[email protected\]](/cdn-cgi/l/email-protection) if: always() with: name: playwright\-report path: playwright\-report/ retention-days: 30

Otimizações

• a imagem básica gcr.io/google.com/cloudsdktool/cloud-sdk é relativamente grande. Você pode criar sua própria imagem gcloud pequena com componentes do Cloud Run para acelerar as compilações.

Conclusão

Status de implantação do GitHub concluído

Os comentários sobre as solicitações pull do GitHub são fáceis no início, mas quando você tem várias implantações por solicitação pull, compilações com falha, etc., elas não oferecem muita flexibilidade e são difíceis de manter/atualizar. A API de implantações do GitHub oferece uma maneira elegante de criar e gerenciar implantações de qualquer sistema de CI/CD de terceiros. Com o GitHub Deployer tentamos simplificar a interação com a API de implantações e cuidar de alguns efeitos colaterais ou armadilhas impossíveis de resolver apenas com a API HTTP.

Outro benefício de usar a API GitHub Deployments é que você pode usar o gatilho deployment_status para GitHub Actions e obter o environment_url diretamente com a carga útil do evento.

Você pode encontrar instruções de instalação/construção um pouco mais detalhadas e todo o código no repositório GitHub

Se você tiver alguma dúvida ou comentário , entre em contato pelo BlueSky / Twitter ou participe da discussão no GitHub .

Também publicado aqui.