Guia de atualização de servidor (deploy-agent)

Processo padrão para DEV/QAS via deploy-agent. SSH manual permanece como contingência.

Documentação do agent: deploy-agent/docs/README.md.

Pré-requisitos

deploy-agent instalado no host (systemd ou processo equivalente)
Docker + Compose e checkout em DEPLOY_AGENT_DEPLOY_ROOT (ecosif-structure)
Chave em DEPLOY_AGENT_API_KEYS (CI: secrets DEPLOY_*)

Fluxo recomendado (API async)

1) Health

curl http://<host>:8787/health

2) Disparar deploy — DEV

curl -X POST "http://<host>:8787/v1/deploy" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "github-actions",
    "key": "<SUA_CHAVE>",
    "service": "",
    "branch": "develop",
    "environment": "dev",
    "async": true
  }'

Resposta esperada: HTTP 202 com request_id e status: queued.

3) Acompanhar

curl -H "X-Deploy-User: github-actions" -H "X-API-Key: <SUA_CHAVE>" \
  "http://<host>:8787/v1/deploy/<request_id>"

Aguarde status em success ou failed. Etapas: sync → recreate → stabilize → verify.

4) Deploy de um serviço — QAS (síncrono, debug)

curl -X POST "http://<host>:8787/v1/deploy" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "ops",
    "key": "<SUA_CHAVE>",
    "service": "ecosif-auth",
    "branch": "qas",
    "environment": "qas",
    "async": false
  }'

5) Validar

JSON (status, steps, commit, error)
Health dos serviços (Traefik / URLs do ambiente)
Arquivo de auditoria (DEPLOY_AGENT_HISTORY_FILE)

CI DEV (opt-in `#publish`)

Workflow: .github/workflows/deploy-dev-from-root.yml

Gatilho	Comportamento
Push em `develop` com `#publish` na mensagem	Build/recreate só dos módulos cujo ponteiro ou path mudou (ex.: `ecosif-reports`); full se structure/database/flyway ou `#publish` sem módulo
Push sem `#publish`	Não publica
`workflow_dispatch`	Publica manualmente (inputs: service, force_rebuild, force_full)

O agent sempre sincroniza o git/submodules; o CI envia apenas o serviço a rebuildar. Poll de status a cada 30s.

Exemplo de mensagem:

feat(auth): ajusta claim de filial

#publish

MVP2: publicar também a partir de feature/* e feat/ (prefixos no agent + workflow).

O gate legado .build-approval não é mais obrigatório para o workflow DEV (substituído por #publish).

Contingência: SSH + scripts do structure

ssh usuario@servidor
cd /opt/ds-ecosif-ia-services/ecosif-structure

./scripts/update-submodules.sh develop   # ou qas

# Preferir o agent; se necessário, Compose direto:
docker compose -f docker-compose.yml -f docker-compose.dev.yml build ecosif-auth
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --force-recreate ecosif-auth

Scripts auxiliares do hub: scripts/checkout-branch.sh, scripts/sync-submodules.sh.

Material legado

Passos longos de migração pontual foram arquivados em
legacy/deploy-obsoleto/guia-atualizacao-servidor-pre-ec011-java17-qas.md.