Use esta checklist de entrega do código-fonte para exportar, documentar, rotacionar segredos, executar migrações, validar builds e confirmar a propriedade do deploy com os clientes.

Uma entrega do código-fonte é o momento em que o projeto deixa de ser “algo que a agência mantém” e passa a ser “algo que o cliente pode possuir”. Sem uma entrega clara, problemas comuns aparecem rápido: o app só compila em um laptop, a produção depende de um segredo que ninguém encontra, ou uma pequena atualização vira dias de tentativa e erro.
O objetivo de qualquer checklist de entrega do código-fonte é simples: depois da transferência, o cliente consegue compilar, rodar e implantar o produto sem precisar da agência de plantão. Isso não significa “sem suporte nunca”. Significa que o básico é repetível e documentado, para que a próxima pessoa consiga dar continuidade com confiança.
O que conta como entregáveis deve ser explícito. No mínimo, uma entrega completa normalmente inclui:
O escopo importa tanto quanto o conteúdo. Algumas entregas cobrem apenas um ambiente (por exemplo, produção). Outras incluem dev, staging e produção com configurações e processos separados. Se você não nomear quais ambientes estão incluídos, as pessoas supõem coisas diferentes — e é aí que ocorrem as quedas.
Uma forma prática de definir sucesso é um teste de verificação: uma pessoa que não construiu o app consegue exportar o código (por exemplo, a partir de uma plataforma como Koder.ai), seguir a documentação, configurar variáveis de ambiente, rodar migrações, compilar e implantar no ambiente combinado.
Este checklist foca na prontidão técnica: variáveis de ambiente, rotação de segredos, migrações de banco, scripts de deploy e verificação de build. Não cobre termos legais, contratos, cláusulas de IP ou disputas de pagamento. Isso também importa, mas pertence a um acordo separado.
Uma entrega limpa começa antes de qualquer exportação. Se você concorda sobre quem possui o quê e quando, evita surpresas de última hora como deploys quebrados, hospedagem não paga ou acessos faltantes.
Escolha uma data de entrega e defina uma janela de congelamento (frequentemente 24–72 horas) em que só correções urgentes são aceitas. Isso mantém o código exportado e o sistema em execução sincronizados. Se um hotfix for necessário durante o congelamento, registre exatamente o que mudou e garanta que esteja incluído na exportação final.
Decidam quem ficará com DNS, hospedagem na nuvem e quaisquer serviços pagos após a entrega. Isso não é só papelada. Se o faturamento permanecer no cartão da agência, serviços podem ser suspensos sem aviso.
Uma forma rápida de tornar isso concreto:
Escreva isso em linguagem simples para que ambos os lados possam seguir.
Combine quais ambientes existem (local, staging, produção) e onde cada um roda. Observe se o staging é um servidor separado, um banco de dados separado ou apenas uma flag de recurso. Se você usou uma plataforma como Koder.ai, confirme também o que está hospedado lá vs o que se espera rodar na infraestrutura do cliente após a exportação.
Não deixe para o último dia solicitar acessos. Garanta que as pessoas certas possam alcançar o que precisam: o repositório, CI, hospedagem, banco de dados e provedor de e-mail.
Combine também o teste final de aceitação e o processo de sign-off. Por exemplo: “O cliente consegue compilar a partir de uma máquina limpa, rodar migrações, implantar no staging e passar no smoke test. Então ambos assinam o aceite por escrito.”
Um bom checklist de entrega do código-fonte começa com um repositório que uma nova equipe consegue abrir e entender em minutos. Confirme o que está incluído (código do app, templates de configuração, scripts) e o que está intencionalmente ausente (segredos reais, chaves privadas, arquivos grandes gerados). Se algo estiver excluído, diga onde fica e quem é o dono.
Mantenha a estrutura previsível. Busque pastas de topo claras como frontend/, backend/, mobile/, infra/, scripts/ e docs/. Se o projeto for um monorepo, explique como as partes se relacionam e como executar cada uma.
O README deve ser utilizável por alguém que não construiu o projeto. Deve cobrir pré-requisitos e o caminho mais rápido para um ambiente de desenvolvimento funcionando, sem adivinhações.
Inclua uma seção breve no README que responda:
Adicione notas de arquitetura simples em linguagem comum: o que fala com o que e por quê. Um pequeno diagrama é opcional, mas algumas frases geralmente bastam. Exemplo: “Frontend React chama a API em Go. A API lê e grava no PostgreSQL. Jobs em background rodam como um processo worker separado.”
Por fim, inclua um changelog versionado ou notas de release para a build de entrega. Pode ser um CHANGELOG.md ou um arquivo curto de “release notes” que indique o commit/tag exato, o que foi entregue e problemas conhecidos.
Se o código foi exportado de uma plataforma como Koder.ai, registre o tipo de projeto gerado (web, server, mobile), a toolchain esperada (por exemplo React, Go, PostgreSQL, Flutter) e as versões de OS/ferramentas suportadas que o cliente deve usar para reproduzir o build.
Variáveis de ambiente são frequentemente a razão de um “app funcionando” falhar logo após a entrega. Um bom checklist trata as variáveis como parte do produto, não como um detalhe.
Comece escrevendo um inventário que uma nova equipe possa seguir sem adivinhações. Mantenha em linguagem simples e inclua um exemplo de formato de valor (não segredos reais). Se uma variável for opcional, diga o que acontece quando está ausente e qual default é usado.
Uma forma simples de apresentar o inventário é:
Destaque diferenças específicas por ambiente. Por exemplo, o staging pode apontar para um banco de testes e um provedor de pagamento sandbox, enquanto produção usa serviços ao vivo. Também registre valores que precisam bater entre sistemas, como URLs de callback, origens permitidas ou identificadores de bundle mobile.
Documente onde cada valor vive hoje. Muitas equipes dividem valores entre lugares: .env locais para desenvolvimento, variáveis de CI para builds e configurações de hospedagem para runtime. Se você usou uma plataforma como Koder.ai para exportar o app, inclua um arquivo .env.example e uma nota curta sobre quais variáveis precisam ser preenchidas antes do primeiro build.
Por fim, prove que não há segredos escondidos no repositório. Não basta checar os arquivos atuais. Revise o histórico de commits em busca de chaves acidentais, .env antigos ou credenciais copiadas em configs de exemplo.
Exemplo concreto: um frontend React + uma API Go podem precisar de API_BASE_URL para o web app, e DATABASE_URL mais JWT_SIGNING_KEY para o backend. Se o staging usa um domínio diferente, escreva ambos os valores e diga onde alterá-los, para que a nova equipe não envie configurações de staging para produção.
Uma entrega não está completa até que o cliente controle todas as credenciais que o app precisa. Isso significa rotacionar segredos, não apenas compartilhá-los. Se uma agência (ou um ex-contratado) ainda tem chaves válidas, você mantém uma porta aberta que não pode auditar.
Comece fazendo um inventário completo. Não pare em senhas de banco. Inclua chaves de API de terceiros, segredos de clientes OAuth, segredos de assinatura de webhooks, chaves de assinatura JWT, credenciais SMTP, chaves de acesso a storage e quaisquer tokens “temporários” em CI.
Aqui vai um checklist simples para o dia da rotação:
Após a rotação, prove que nada quebrou. Rode testes rápidos com “fluxos de usuário real” em vez de checar só logs.
Foque em fluxos que dependem de segredos:
Exemplo: se você exportou um projeto de Koder.ai e o app usa um provedor de pagamento e envio de e-mail, rotacione ambas as chaves, redeploy em staging, então faça uma pequena transação de teste e envie um e-mail de teste. Só após o sucesso revogue as chaves da agência.
Por fim, documente onde os segredos ficarão daqui para frente (vault, variáveis de CI ou configurações de hospedagem), quem pode alterá-los e como reverter com segurança se uma rotação causar erros.
Uma entrega pode parecer “concluída” enquanto o banco de dados é a parte que quebra primeiro. Trate migrações e dados como um produto próprio: versionado, repetível e testado.
Comece anotando a versão atual do banco e onde as migrações ficam no repositório. Seja específico: o caminho da pasta, padrão de nomes e o último ID de migração (ou timestamp). Se você usa PostgreSQL (comum em backends Go), também anote extensões necessárias.
Inclua um runbook curto que responda a estas perguntas:
Rollbacks merecem honestidade. Algumas mudanças só são reversíveis com restauração de backup. Aponte isso em linguagem clara e associe a um passo de backup (snapshot antes do deploy, verificação do processo de restore).
Antes de concluir a entrega, execute migrações em uma cópia dos dados de produção se possível. Isso detecta queries lentas, índices ausentes e problemas de “funciona com dados vazios”. Um teste realista é exportar o código, configurar variáveis, restaurar um dump anonimizável e aplicar as migrações do zero. Esse exercício valida grande parte do checklist.
Se o app foi construído em uma plataforma como Koder.ai e depois exportado, verifique se arquivos de migração e scripts de seed estão incluídos na exportação e ainda são referenciados corretamente pelo processo de inicialização do backend.
A entrega só está completa quando outra pessoa consegue rebuildar o app do zero em uma máquina limpa. Seu checklist deve incluir os comandos exatos de build, versões necessárias e o output esperado (por exemplo: “bundle web em /dist”, “binário da API com nome X”, “APK do Flutter em local Y”).
Registre as ferramentas e os gerenciadores de pacotes que você realmente usa, não o que você acha que usa. Em stacks típicas isso pode ser Node.js (npm ou pnpm) para React, toolchain Go para o servidor, ferramentas do PostgreSQL para setup local e SDK do Flutter para mobile.
Torne a instalação de dependências previsível. Confirme que lockfiles estão comitados (package-lock.json, pnpm-lock.yaml, go.sum, pubspec.lock) e faça uma instalação limpa em um computador novo ou container limpo para provar que funciona.
Capture o que o CI faz, passo a passo, para que possa ser copiado para outro provedor de CI se necessário:
Separe configuração de build da configuração de runtime. Configuração de build muda o que é compilado (por exemplo, uma API base URL embutida no bundle web). Configuração de runtime é injetada na inicialização (como URLs de banco, chaves de API e flags de recurso). Misturar os dois é uma causa comum de “funciona no CI” mas falha no deploy.
Forneça uma receita simples de verificação local. Mesmo um conjunto curto de comandos já é suficiente:
# Web
pnpm install
pnpm test
pnpm build
# API
go test ./...
go build ./cmd/server
# Mobile
flutter pub get
flutter test
flutter build apk
Se você está exportando de uma plataforma como Koder.ai, inclua quaisquer arquivos de CI gerados ou presets de build usados durante o deploy para que o cliente reproduza o mesmo build fora da plataforma.
Um bom checklist de entrega não para em “aqui está o repositório”. Ele também explica como o app sai do código e vira um serviço em execução, e quem aperta o botão.
Comece anotando como os deploys acontecem hoje: totalmente manuais (alguém executa comandos em um servidor), acionados por CI (pipeline que builda e deploya) ou via plataforma hospedada. Inclua onde as configs ficam e quais ambientes existem (dev, staging, produção).
Torne os passos de release repetíveis. Se o processo depende de uma pessoa lembrando 12 comandos, transforme isso em scripts e registre as permissões necessárias.
Dê ao cliente o suficiente para implantar no primeiro dia:
Entrem em acordo sobre expectativas de downtime. Se “zero downtime” é exigido, diga o que isso significa na prática (blue-green, rolling deploy, janela de leitura apenas para migrações). Se downtime é aceitável, defina uma janela clara.
Ativos estáticos e caches são pontos comuns de falha. Anote como os assets são gerados e servidos, quando invalidar caches e se há um CDN envolvido.
Um rollback deve ser uma receita curta e testada ligada a uma tag ou ID de release. Por exemplo: deployar a tag anterior, restaurar o snapshot do banco se necessário e invalidar caches.
Se o app foi criado no Koder.ai e depois exportado, mencione o último snapshot conhecido como bom e a versão exata da exportação para que o cliente correlacione código com uma release funcional rapidamente.
A verificação é o momento em que você descobre se a entrega é real. O objetivo é simples: alguém novo pega o código exportado, configura e obtém o mesmo app rodando sem adivinhações.
Antes de começar, registre o que significa “correto”: a versão do app em execução, o commit/tag atual (se houver) e uma ou duas telas ou respostas de API-chave para comparar. Se a exportação veio de uma plataforma como Koder.ai, note o timestamp do snapshot/export para provar que testou o estado mais recente.
Para smoke tests, mantenha curto e focado em risco:
Se algo falhar, capture o comando exato, a saída de erro e as variáveis de ambiente usadas. Esse detalhe economiza horas quando a propriedade muda de mãos.
A forma mais rápida de transformar uma entrega em um incêndio é assumir “o código é suficiente”. Um bom checklist foca nos detalhes pequenos e chatos que decidem se o cliente consegue realmente rodar e modificar o app sem você.
A maior parte dos problemas segue alguns padrões:
Torne rotação e limpeza de acessos uma tarefa agendada, não um item “quando der tempo”. Defina uma data em que contas da agência são removidas, chaves de serviço são regeneradas e o cliente confirma que consegue implantar apenas com credenciais próprias.
Para variáveis de ambiente, faça um inventário simples em três lugares: repositório, sistema de CI e UI de hospedagem. Depois valide rodando um build limpo em uma máquina/container novo.
Para migrações, teste com o mesmo papel de banco que o deploy de produção usará. Se produção requer passos elevados (como habilitar uma extensão), documente-os e deixe claro quem é o responsável.
Um exemplo realista: após exportar um projeto de Koder.ai, o cliente faz deploy com sucesso mas jobs em background falham porque uma URL de fila estava só definida no dashboard de hospedagem. Uma auditoria rápida de variáveis teria detectado. Junte isso a uma release tag e um rollback documentado (por exemplo, “redeploy da tag v1.8.2 e restore do último snapshot”) para evitar downtime.
Se você só guardar uma página deste checklist de entrega do código-fonte, guarde esta. O objetivo é simples: um clone limpo deve rodar em uma máquina nova, com segredos novos, e um banco que possa evoluir com segurança.
Execute estas verificações em um laptop que nunca viu o projeto (ou em um container/VM limpo). Essa é a forma mais rápida de achar arquivos faltantes, suposições ocultas e credenciais antigas.
Uma agência entrega um frontend React, uma API Go e um banco PostgreSQL. A equipe do cliente clona o repo, copia o .env.example para variáveis reais, e cria credenciais novas para o banco, provedor de e-mail e APIs de terceiros. Eles rodam go test (ou o comando de teste acordado), constroem o app React, aplicam migrações em uma instância Postgres limpa e iniciam ambos os serviços. Por fim, fazem o deploy usando o script documentado e confirmam que o mesmo commit pode ser rebuildado depois.
Mantenha a entrega curta e com um responsável. Uma walkthrough de 30 a 60 minutos geralmente vale mais que um documento longo.