Repository navigation
CI CD e Deploy
Para quem é este artigo: para quem quer entender como o PolicyDesk é verificado e publicado, e para quem está aprendendo CI/CD, GitHub Actions e Azure.
Pré-requisitos: saber o que é um commit e um pull request no Git. O resto é explicado do zero.
O que você vai aprender: o que são CI e CD, os conceitos do GitHub Actions, cada passo do pipeline do PolicyDesk, como o deploy entra na Azure sem guardar senhas, a infraestrutura como código com Bicep e como fazer o primeiro deploy.
Sem automação, publicar uma versão nova é uma lista de passos manuais: compilar, rodar os testes (se alguém lembrar), gerar o pacote, entrar no servidor, copiar os arquivos, atualizar o banco, reiniciar. Cada passo é uma chance de erro, e cada pessoa faz de um jeito. Pior: quem garante que o código que foi para produção é o mesmo que passou nos testes?
CI/CD é a resposta da indústria para isso:
- CI, Integração Contínua (Continuous Integration): a cada mudança enviada ao repositório, um servidor compila o código e roda todos os testes automaticamente. Se algo quebrar, a equipe sabe em minutos, e não na semana do lançamento.
- CD, Entrega Contínua (Continuous Delivery/Deployment): toda versão que passa no CI é empacotada e publicada automaticamente, sempre pelo mesmo caminho.
O resultado: publicar deixa de ser um evento arriscado e vira algo rotineiro, que acontece a cada merge.
O PolicyDesk usa o GitHub Actions, o serviço de automação do próprio GitHub. Os conceitos:
| Conceito | O que é | No PolicyDesk |
|---|---|---|
| Workflow | Um processo automatizado, descrito em um arquivo YAML em .github/workflows/
|
ci.yml, cd.yml, codeql.yml
|
Evento (on:) |
O que dispara o workflow | Um push, um pull request, um horário, um clique manual |
| Job | Um conjunto de passos que roda em uma máquina |
Build e testes, Empacotar, Deploy em produção
|
| Runner | A máquina virtual que executa o job, criada do zero e descartada no final |
ubuntu-latest, já com Docker e Git |
| Step | Um passo dentro do job: um comando ou uma action |
dotnet build, dotnet test
|
| Action | Um passo pronto e reutilizável, publicado por alguém |
actions/checkout@v4 baixa o código; actions/setup-dotnet@v4 instala o .NET |
| Artefato | Um arquivo produzido por um job e guardado para os próximos jobs (ou para download) | A API publicada, o bundle de migrations, o relatório de cobertura |
| Secret | Um valor sensível, guardado criptografado pelo GitHub e nunca exibido nos logs |
AZURE_CLIENT_ID, DATABASE_CONNECTION_STRING
|
| Environment | Um ambiente de destino (como "produção"), com secrets próprios e regras de proteção |
production, que só aceita deploy a partir da main
|
Um workflow mínimo, para fixar a sintaxe:
name: CI
on:
pull_request: # dispara em todo pull request
jobs:
build:
runs-on: ubuntu-latest # a máquina
steps:
- uses: actions/checkout@v4 # uma action pronta: baixa o código
- run: dotnet test # um comandoEle publica a API em um Azure App Service Linux no plano F1 (gratuito), com um Azure Database for PostgreSQL Flexible Server.
Arquivos envolvidos:
| Arquivo | Papel |
|---|---|
.github/workflows/ci.yml |
Integração contínua: build, auditoria de pacotes, testes e cobertura |
.github/workflows/cd.yml |
Entrega contínua: empacota e publica na Azure |
.github/workflows/codeql.yml |
Análise estática de segurança |
.github/dependabot.yml |
Atualização automática de dependências |
infra/main.bicep |
Infraestrutura como código (banco, plano F1, Web App) |
infra/bootstrap.sh |
Provisiona a Azure e configura o GitHub com um comando |
global.json |
Fixa a versão do SDK do .NET |
.config/dotnet-tools.json |
Fixa a versão do dotnet-ef
|
flowchart LR
PR["Pull request<br/>ou push em developer"] --> CI
MAIN["Merge em main"] --> CD_CI
subgraph CD["cd.yml"]
CD_CI["CI<br/>(reutilizado)"] --> PKG["Empacotar<br/>dotnet publish<br/>migrations bundle"]
PKG --> DEP["Deploy (environment production)<br/>login OIDC · migrations<br/>App Service · smoke test"]
end
CI["<b>ci.yml</b><br/>restore · vulnerabilidades<br/>build · testes · cobertura"]
| Evento | O que roda |
|---|---|
Pull request para main ou developer
|
CI e CodeQL |
Push em developer
|
CI e CodeQL |
Push em main (merge) |
CD (que inclui o CI) e CodeQL |
| Toda segunda-feira | CodeQL e Dependabot |
Manual (workflow_dispatch) |
CI ou CD, pela aba Actions |
Mudanças só em Markdown, docs/ ou LICENSE não disparam CI nem CD (paths-ignore).
Um único job, Build e testes, em ubuntu-latest:
| Passo | Comando | Por quê |
|---|---|---|
| SDK |
actions/setup-dotnet com global-json-file
|
A mesma versão do SDK local, sem número repetido no YAML |
| Cache |
actions/cache em ~/.nuget/packages
|
A chave usa Directory.Packages.props e os .csproj: muda só quando as dependências mudam |
| Restore | dotnet restore |
Separado do build, para o cache ter efeito |
| Vulnerabilidades | dotnet list package --vulnerable --include-transitive |
Falha se algum pacote, mesmo indireto, tiver vulnerabilidade conhecida |
| Build | dotnet build -c Release |
Com TreatWarningsAsErrors, qualquer aviso de analisador ou de estilo quebra o CI |
| Testes | dotnet test --collect "XPlat Code Coverage" |
Os quatro projetos. O runner tem Docker, então os testes com Testcontainers rodam contra um PostgreSQL de verdade |
| Cobertura | ReportGenerator | Consolida os relatórios e publica o resumo na página da execução |
| Artefatos | actions/upload-artifact |
Resultados .trx e o relatório HTML de cobertura, por 14 dias |
Decisões:
-
permissions: contents: readno workflow inteiro. OGITHUB_TOKENnão pode escrever nada. -
concurrencycomcancel-in-progress: um push novo na mesma branch cancela a execução anterior, que já ficou obsoleta. -
workflow_call: o CD reaproveita este mesmo workflow, em vez de copiar os passos. -
timeout-minutesem todos os jobs. Um teste travado não consome horas de runner.
O CI não roda
dotnet format --verify-no-changes. O build já aplica as regras de estilo do.editorconfig(EnforceCodeStyleInBuild), e odotnet formatainda acusa diferenças que o build aceita (ordem deusingem alguns testes e quebra de linha no fim de arquivo). Adicionar essa verificação exige limpar o código antes.
Três jobs em sequência. Se um falha, os seguintes não rodam.
ci:
uses: ./.github/workflows/ci.ymlNada vai para produção sem passar pelos mesmos testes de um pull request.
dotnet publish src/Backend/PolicyDesk.Api/PolicyDesk.Api.csproj \
--configuration Release --output artifacts/api \
-p:UseAppHost=false -p:SourceRevisionId=$GITHUB_SHA
dotnet ef migrations bundle --self-contained --runtime linux-x64 \
--project src/Backend/PolicyDesk.Infrastructure \
--startup-project src/Backend/PolicyDesk.Infrastructure \
--output artifacts/migrations/efbundleGera dois artefatos: a API publicada e o migrations bundle, um executável autocontido com todas as migrations. O SourceRevisionId grava o commit na versão do assembly, o que permite saber exatamente qual código está no ar.
O princípio é build once, deploy many: o job de deploy não compila nada, só baixa o que foi gerado aqui.
Roda no environment production do GitHub, que guarda os secrets e só aceita deploy a partir da main.
| Passo | O que faz |
|---|---|
| Baixar artefatos | API e bundle gerados no job anterior |
| Login na Azure |
azure/login com OIDC (sem senha) |
| Migrations |
./efbundle --connection "$DB_CONNECTION", antes de publicar a API |
| Deploy |
azure/webapps-deploy envia o pacote ao Web App |
| Smoke test |
curl --retry 12 em /health, que só responde 200 se a API subiu e o banco responde |
| Logout |
az logout, mesmo se algo falhar |
O concurrency: deploy-production sem cancelamento garante que dois deploys nunca rodem ao mesmo tempo, e que um deploy em andamento não seja interrompido no meio.
Por que migrar antes de publicar? A versão nova da API pode depender de colunas novas. A ordem inversa deixaria a API nova no ar, por alguns segundos, com o banco antigo. Em troca, cada migration precisa ser compatível com a versão anterior da API, que continua no ar até o deploy terminar. Remover ou renomear uma coluna é feito em duas entregas (expand/contract). Mais em Persistência › Migrations bundle.
O pipeline não guarda senha nem publish profile da Azure. Em cada execução:
sequenceDiagram
participant GH as GitHub Actions
participant ID as Microsoft Entra ID
participant AZ as Azure
GH->>GH: emite um token OIDC de curta duração<br/>(sub = repo:Rodrigosdk/PolicyDesk:environment:production)
GH->>ID: troca o token (federated credential)
ID-->>GH: token de acesso da identidade github-policydesk-api-rodrigo
GH->>AZ: deploy com o token de acesso
- A federated credential só aceita tokens do repositório e do environment
production. Um workflow de outra branch, ou de um fork, não consegue o acesso. - A identidade tem só o papel Website Contributor, e só sobre o Web App. Não acessa o banco, outros recursos nem a assinatura.
- O job pede
id-token: writesó para si. Os outros jobs não podem emitir tokens.
Os valores ficam no environment production:
| Tipo | Nome | Conteúdo |
|---|---|---|
| Secret | AZURE_CLIENT_ID |
Id da identidade do GitHub Actions |
| Secret | AZURE_TENANT_ID |
Tenant do Entra ID |
| Secret | AZURE_SUBSCRIPTION_ID |
Assinatura da Azure |
| Secret | DATABASE_CONNECTION_STRING |
Connection string usada pelas migrations |
| Variable | AZURE_WEBAPP_NAME |
policydesk-api-rodrigo |
Se a extensão do GitHub Actions no editor acusar
Context access might be invalid: AZURE_WEBAPP_NAME, é só porque a variável ainda não existe no repositório. O aviso some quando ela é cadastrada.
| Ferramenta | Quando | O que encontra |
|---|---|---|
dotnet list package --vulnerable |
Todo CI | Pacotes NuGet com vulnerabilidade publicada (GitHub Advisory Database) |
CodeQL (security-and-quality) |
PRs, pushes e semanalmente | Injeção de SQL, caminhos inseguros, exceções engolidas e outros problemas no código C# |
| Dependabot | Semanalmente | PRs com atualizações de NuGet, Actions e imagens Docker, agrupadas e apontadas para developer
|
Os grupos do Dependabot (microsoft, opentelemetry, testes) juntam pacotes que costumam ser atualizados juntos. Uma versão nova do EF Core chega em um PR só, e não em seis.
flowchart LR
subgraph RG["rg-policydesk (brazilsouth)"]
PLAN["plan-policydesk-api-rodrigo<br/>App Service Plan F1 Linux"] --> APP["policydesk-api-rodrigo<br/>Web App .NET 10"]
PG["psql-policydesk-api-rodrigo<br/>PostgreSQL 17 · B1ms"] --> DB[("policydesk")]
end
APP -- "SSL Mode=Require" --> DB
GH["GitHub Actions"] -- "migrations" --> DB
GH -- "deploy" --> APP
| Recurso | Configuração | Por quê |
|---|---|---|
| PostgreSQL Flexible Server |
Standard_B1ms, 32 GB, PostgreSQL 17 |
B1ms faz parte da oferta gratuita de 12 meses da Azure |
| Firewall do banco | AllowAllAzureServicesAndResourcesWithinAzureIps |
O App Service e os runners do GitHub (que rodam na Azure) alcançam o banco sem abrir para a internet toda. Rede privada exigiria um plano pago |
| App Service Plan |
F1, Linux |
Gratuito |
| Web App |
DOTNETCORE|10.0, httpsOnly, TLS 1.2, FTP desligado |
Só HTTPS, sem protocolos legados |
ASPNETCORE_ENVIRONMENT |
Production |
Sem Swagger e sem migrations na inicialização |
ASPNETCORE_FORWARDEDHEADERS_ENABLED |
true |
O App Service termina o TLS no balanceador. Sem isso, a API acharia que a requisição chegou por HTTP |
SCM_DO_BUILD_DURING_DEPLOYMENT |
false |
O pacote já chega compilado; o App Service não tenta compilar de novo |
| Connection string | Tipo Custom, nome DbConnection
|
Vira a variável CUSTOMCONNSTR_DbConnection, que o ASP.NET Core lê como ConnectionStrings:DbConnection
|
Bicep é a linguagem de infraestrutura como código da própria Azure. Ele é declarativo e idempotente: rodar de novo só ajusta o que mudou.
| Limite | Consequência |
|---|---|
| 60 minutos de CPU por dia | Suficiente para demonstração; tráfego real esgota a cota |
| Sem Always On | A aplicação dorme sem uso. A primeira requisição depois disso leva alguns segundos |
| Sem deployment slots | Não há troca de slot (blue-green). Cada deploy tem um pequeno intervalo fora do ar, e o rollback é reimplantar a versão anterior |
| 1 GB de memória e de disco | Suficiente para a API |
Em um ambiente real, o plano B1 ou superior habilita Always On, e o S1 habilita slots de deploy sem downtime.
Pré-requisitos: Azure CLI e GitHub CLI autenticados (az login e gh auth login) e uma assinatura da Azure ativa.
./infra/bootstrap.shO script, que pode ser rodado de novo sem duplicar nada:
- Cria o grupo de recursos
rg-policydeskembrazilsouth. - Gera uma senha aleatória para o banco e aplica o
main.bicep(banco, plano F1 e Web App, com a connection string configurada). - Cria a identidade do GitHub Actions, a federated credential do environment
productione o papelWebsite Contributorno Web App. - Configura o environment
productionno GitHub para aceitar deploy só damain. - Cadastra os quatro secrets e a variável do environment.
Depois disso, um merge em main publica a API em https://policydesk-api-rodrigo.azurewebsites.net.
Variáveis opcionais: APP_NAME (padrão policydesk-api-rodrigo), RESOURCE_GROUP, LOCATION, GITHUB_REPO e DB_ADMIN_PASSWORD. Rodar o script de novo sem DB_ADMIN_PASSWORD troca a senha do banco, e o script atualiza ao mesmo tempo o Web App e o secret.
| Erro | Causa | Solução |
|---|---|---|
A conta logada não tem assinatura da Azure |
az login com uma conta sem assinatura |
Criar uma assinatura e fazer az login de novo |
Current Limit (F1 VMs): 0 |
Assinaturas novas vêm com cota zero de App Service | Pedir a cota no portal: Quotas › App Service, região Brazil South, limite 1 para F1 |
The selected region is currently not accepting new customers |
Região sem capacidade para assinaturas novas | Usar outra região com LOCATION=...
|
| Smoke test falha com 503 | A API subiu, mas não alcança o banco | Conferir o firewall do PostgreSQL e o secret DATABASE_CONNECTION_STRING
|
| Migrations falham com timeout | O runner não alcança o banco | Conferir a regra AllowAllAzureServicesAndResourcesWithinAzureIps
|
- Execuções: aba Actions do repositório. O resumo de cada CI mostra a cobertura.
-
Deploys: o environment
productionregistra cada deploy, com o commit e a URL. - Logs da API em produção: veja Observabilidade › Em produção.
-
Fixar as Actions por SHA (
actions/checkout@<sha>) em vez de@v4. Protege contra uma tag movida maliciosamente; o Dependabot continua atualizando. -
Aprovação manual no environment
production(required reviewers), para que o deploy espere um clique. -
Verificação de formatação no CI, depois de alinhar o código ao
dotnet format. -
Imagem de contêiner publicada no GitHub Container Registry, reaproveitando o
docker/Dockerfile, para rodar a mesma imagem em qualquer nuvem. -
Ambiente de homologação, com deploy automático a partir da
developer.
- CI compila e testa cada mudança; CD publica cada versão aprovada, sempre pelo mesmo caminho.
- O CD reaproveita o CI, gera os artefatos uma vez e publica exatamente o que foi testado.
- O login na Azure usa OIDC: nenhuma senha de longa duração fica guardada, e a identidade só pode mexer no Web App.
- As migrations rodam antes de publicar a API, e um smoke test confirma que tudo subiu.
- A infraestrutura é código (Bicep), e um único script prepara a Azure e o GitHub.
- Documentação do GitHub Actions: "Understanding GitHub Actions" e "Security hardening with OpenID Connect".
- Documentação da Azure: "Deploy to App Service using GitHub Actions" e "What is Bicep?".
- Continuous Delivery, Jez Humble e David Farley.
- Accelerate, Nicole Forsgren, Jez Humble e Gene Kim: a pesquisa que relaciona práticas de entrega com o desempenho das equipes.
PolicyDesk · Distribuído sob a licença MIT · Repositório
Comece aqui
Como o sistema é feito
A API
Engenharia
Prática
Consulta