Tutorial: do commit à Produção

Este tutorial percorre o ciclo de vida de uma Central na Plataforma Oon: do repositório até a Produção, passando por Desenvolvimento e Homologação. Publicação e promoção são serviços da plataforma — o App consome o fluxo e não o reimplementa.

commit → Publicar em Dev → Desenvolvimento → Promover para Homologação
       → Aceitar homologação → Promover para Produção → (Reverter, se preciso)

Pré-requisitos

• Uma organização no Meus Apps em que o seu papel seja owner ou dev.
• Uma conta GitHub. O código fica em um repositório seu; a plataforma registra o App, o vínculo e as publicações.
• Para desenvolver localmente: Node.js e MongoDB, como no Quickstart.

1. Crie o App no Workspace

1. No Meus Apps, abra Desenvolvimento e Suporte → Workspace e escolha a organização-alvo. O App pertence a essa organização, e a propriedade não pode ser transferida.
2. Em Vincular conta GitHub, autorize a GitHub App Oon Workspace na conta ou organização onde o repositório vai ficar. O Workspace não pede PAT nem senha.
3. Em Oon Apps → Criar Oon-App, escolha a finalidade (Uso da própria organização, Licenciamento exclusivo ou Licenciamento para múltiplos clientes), a origem do código e o nome.

Com repositório novo, a plataforma cria um repositório privado com o scaffold oficial e o workflow de publicação. Com repositório existente, nada é alterado: o repositório precisa ter central.app.json, oon.deploy.json (com o mesmo código do App) e .github/workflows/publish-dev.yml.

2. Desenvolva e valide localmente

Clone o repositório, rode npm run dev e construa o domínio — por exemplo, seguindo o tutorial da central de compras. Antes de cada publicação:

npm run check
npm run build --prefix frontend

O check executa o doctor: versões coordenadas do Core, lockfiles, manifestos, cache .ooncore/ e conformance. Commite código, manifestos, lockfiles e .ooncore/ — o que não está no commit não chega à imagem. Veja Testes, doctor e conformance e Empacotamento da imagem.

3. Publique em Desenvolvimento

No cartão do App, em Oon Apps, clique em Publicar em Dev. O Workspace dispara o workflow publish-dev na branch padrão; o workflow se autentica por OIDC do GitHub e pede a release à Central de Ativações, que autoriza, constrói e valida a imagem e faz o deploy.

Também dá para rodar direto no GitHub: Actions → publish-dev → Run workflow. O resumo do job mostra a release aceita:

Publicação Dev aceita: release=rel-minha-central-<sha>-<id> etapa=despachada

Quando o ambiente estiver ativo, use Acessar Dev e confirme a versão publicada:

curl --fail-with-body https://SEU-APP-DEV/api/health/ready
curl --fail-with-body https://SEU-APP-DEV/api/health/version

/health/version informa a versão do Core, o commit, o releaseId e o ambiente.

4. Homologue

Em Desenvolvimento e Suporte → Publicações (no Meus Apps), a tela sugere a próxima etapa permitida.

1. Promover para Homologação — reaproveita a mesma imagem validada em Dev, sem novo build.
2. Teste as jornadas reais em Homologação, com os usuários de negócio.
3. Aceitar homologação — o aceite técnico e de negócio libera a Produção. Em Apps licenciados, Homologação só é aberta ao cliente com liberação explícita.

5. Promova para Produção

Clique em Promover para Produção. A promoção transporta a mesma imagem e a declaração do App; segredos de core.secrets recebem chave independente no destino. Em Produção ficam disponíveis réplicas, domínios personalizados com certificado automático e métricas de uso — veja Publicação e ambientes.

Publicação, promoção, reversão e aceite técnico de Homologação são exclusivos de quem tem permissão técnica no App.

6. Reverta, se precisar

Homologação e Produção podem ser revertidas para a publicação anterior pela mesma tela de Publicações. Quando uma ação está bloqueada, a tela mostra o motivo e o código. Para uma publicação em andamento, use Reconciliar estado na aba Publicação dos detalhes do App.

7. Evolua com novas versões

Cada necessidade nova vira um commit, uma publicação em Dev e o mesmo ciclo de homologação e promoção. Para atualizar o Core, siga Atualizando o Core e acompanhe as novidades em Versões.

Checklist

Próximos passos

• Publicação e ambientes — Fluxo, oon.deploy.json, ambientes e runtime publicado.
• Troubleshooting — Erros comuns de publicação e como diagnosticar.
• Plataforma Oon — Workspace, Central de Ativações, Meus Apps e delivery.