Publicado em
Como publicar uma aplicação do GitHub ou do Forgejo na Zenifra?
Conecte o GitHub (ou uma instância Forgejo) à organização, crie um projeto HTTP com origem em Repositório Git, escolha runtime, comandos e forma de atualização, e a Zenifra instala as dependências, faz a build e publica a aplicação com HTTPS. Depois disso, cada push na branch, cada tag ou cada release que corresponder ao padrão configurado gera uma nova versão, e os Logs de build mostram exatamente onde algo falhou.
Como funciona o deploy pelo GitHub na Zenifra
Você conecta o GitHub (ou uma instância Forgejo) à organização, cria um projeto HTTP com origem em Repositório Git e informa runtime, comandos e forma de atualização. A Zenifra instala as dependências, executa a build, publica a aplicação com HTTPS e, a partir daí, cada push, tag ou release que você escolher vira uma nova versão.
O fluxo tem sempre a mesma ordem, documentada em Runtimes e em Implantação via GitHub: instalação de dependências conforme o runtime (por exemplo, npm ci no Node.js), comando pre-build (opcional), comando build (opcional) e comando start (obrigatório), que é o processo que fica rodando e atende as requisições. Todas as etapas rodam dentro do Diretório raiz do projeto, que por padrão é a raiz do repositório. A Zenifra não detecta o runtime sozinha: você escolhe Node.js, Python, Bun, Go, Java ou PHP na criação do projeto, junto com a versão.
Esse caminho serve para quem quer que a plataforma cuide da build. Se a sua aplicação usa outra linguagem (.NET, Ruby, Rust) ou você já gera uma imagem Docker no seu CI, o caminho é outro: publicar uma Imagem OCI. As duas opções convivem na mesma organização, e você pode ter um projeto de cada tipo lado a lado. Este guia cobre o caminho por repositório Git do início ao fim, com os valores que você preenche no Console e os erros que mais aparecem nos Logs de build.
Antes de começar, tenha três coisas à mão: uma conta Zenifra com a organização certa selecionada, permissão para instalar o GitHub App Zenifra na conta ou organização do GitHub que possui o repositório e a aplicação rodando localmente com os mesmos comandos que você vai configurar. No Node.js, por exemplo, isso significa que npm ci, npm run build e npm start funcionam na sua máquina com a mesma versão principal do Node.js que você vai selecionar no projeto.
Passo 1: conectar o GitHub à organização
A conexão tem duas etapas obrigatórias, e as duas precisam estar concluídas antes de qualquer repositório aparecer no Console. Primeiro, uma pessoa owner da organização vincula a conta GitHub: no console.zenifra.com, com a organização correta selecionada, abra Conta no menu lateral, inicie a conexão na seção do GitHub e autorize o vínculo. Esse vínculo só identifica qual usuário do GitHub a Zenifra vai usar; ele não libera repositórios por si só.
A segunda etapa é instalar o GitHub App Zenifra em github.com/apps/zenifra/installations/new. Na instalação, o GitHub pergunta onde instalar (sua conta pessoal ou uma organização do GitHub) e quais repositórios liberar: Todos os repositórios, que inclui também os futuros, ou Apenas repositórios selecionados. Se você quer limitar o acesso, prefira a seleção manual. Em organizações do GitHub, a instalação pode depender da aprovação de um administrador, e quem trabalha com várias organizações precisa instalar o app em cada uma delas.
Para confirmar que deu certo, volte ao Console, inicie a criação de um projeto com origem GitHub e verifique se a conta e o repositório esperados aparecem. Se a conta aparece, mas um repositório específico não, o vínculo está funcionando e o ajuste está na instalação do app: provavelmente o repositório ficou fora da seleção. Se a conexão não for concluída ao voltar do GitHub, saiba que a autorização vale para um único uso, por até 10 minutos, e só pode ser concluída no mesmo navegador em que foi iniciada; troca de navegador, cookies bloqueados ou o link de retorno aberto duas vezes exigem recomeçar.
Membros que não são owner, mas podem criar projetos, também podem conectar o próprio GitHub em Conta, no cartão Seu GitHub (opcional), com Conectar meu GitHub. Ao criar um projeto, o GitHub da organização continua sendo o padrão; quem conectou o seu escolhe Meu GitHub em Repositórios de. Essa conexão pessoal vale só naquela organização, ninguém mais a usa, e os deploys seguintes, inclusive os automáticos, usam o GitHub App instalado no repositório. Por isso, mantenha o app instalado enquanto o projeto existir.
Passo 1 no Forgejo: conexão por token e hook
Se o código está em uma instância Forgejo, inclusive uma hospedada pela sua empresa, a conexão é feita por token e pertence à organização. Você precisa do endereço HTTPS da instância, com certificado TLS válido e confiável, e a instância precisa estar acessível para a conexão da Zenifra; abrir o endereço no seu navegador não prova isso. Anote também o caminho completo do repositório no formato equipe/aplicacao: a integração não lista nem descobre repositórios, então o caminho é digitado no Console.
O escopo do token depende do que você quer fazer. Para leitura da origem e deploy manual, read:repository basta. Para publicar automaticamente por push, tag, release ou pull request, use write:repository com uma conta que administre os hooks do repositório. A documentação recomenda uma identidade dedicada, com acesso apenas aos repositórios necessários, e o token criado com a opção de acesso All (public, private, and limited); tokens no modo Specific repositories não executam operações administrativas, então não conseguem criar o hook.
A conexão é criada no próprio formulário de projeto: em Configurações avançadas, escolha Repositório Git em Origem do Projeto e Forgejo em Provedor Git. Se ainda não houver uma conexão, uma pessoa owner informa Endereço da instância, Nome da conexão, Caminho do repositório, Usuário e Token de acesso e escolhe Conectar repositório; os demais membros usam as conexões existentes. Não coloque o domínio no caminho do repositório nem o token em URLs ou comandos Git.
Há limites atuais que vale conhecer antes de escolher o Forgejo: não há descoberta de repositórios, origem SSH, submódulos nem Git LFS, e pull requests de forks não geram preview. A integração com GitLab também não está disponível hoje. Cada hook do Forgejo aceita até 120 eventos por minuto, com corpo de até 100 KB por entrega; entregas sem a assinatura do segredo do hook são recusadas com 401.
Passo 2: criar o projeto HTTP no Console
Com a conexão pronta, a criação segue a tela de novo projeto do Console. O nome do projeto tem de 6 a 32 caracteres, só letras minúsculas, números e hífens, e é usado no subdomínio automático. Em seguida vêm o plano, o modelo de pagamento (por hora, mensal ou anual) e as configurações avançadas, onde ficam a origem, a porta, as instâncias, as variáveis de ambiente, o armazenamento e a exposição (pública ou privada).
Na escolha do plano, considere o runtime. O Static (R$ 5,90/mês ou R$ 0,01/h no catálogo de 06/11/2026) tem 0.1 vCPU e 128 MB e foi pensado para servidores HTTP leves como o NGINX; a própria documentação de sites estáticos recomenda Basic ou superior quando a aplicação mantém um processo Node.js rodando. O Basic custa R$ 29,90/mês ou R$ 0,05/h, com 0.5 vCPU e 512 MB. Health check e subdomínio personalizado entram a partir do Premium.
O campo Porta precisa ser igual à porta em que a aplicação escuta, e a aplicação precisa escutar em 0.0.0.0, não em localhost. A documentação sugere 3000 para Node.js e Bun, 8000 para Python e 8080 para Go, Java e PHP, mas o valor que vale é o do seu código. Para produção, a recomendação da documentação é usar pelo menos 2 instâncias. Depois de criar, o projeto recebe uma URL em *.clients.zenifra.com com HTTPS; domínio próprio é configurado em seguida, com até 20 domínios por projeto.
- No Console, clique em Criar projeto e escolha Aplicação HTTP.
- Em Configurações Avançadas, no campo Origem do Projeto, escolha Repositório Git e, em Provedor Git, escolha GitHub (ou Forgejo).
- Selecione o repositório, a branch, o runtime, a versão e os comandos. Se a aplicação estiver em uma subpasta, preencha Diretório raiz (por exemplo, backend ou apps/api).
- Escolha uma das quatro formas de atualização: Manual, Automático por branch (selecionada por padrão), Por Tag ou Por Release.
- Preencha porta, instâncias, variáveis de ambiente e armazenamento e clique em Criar Projeto. A primeira build começa na hora, usando a branch selecionada.
O Diretório raiz aceita só caminhos relativos com / como separador; caminhos absolutos e .. são recusados, ./backend/ equivale a backend, e só o conteúdo dessa pasta entra na build. Arquivos como package.json, package-lock.json e requirements.txt precisam estar dentro dela. Para publicar API e frontend do mesmo monorepo, crie um projeto para cada pasta.
Runtimes, versões e comandos por framework
Os runtimes oficialmente suportados para builds por repositório Git são Node.js, Python, Bun, Go, Java e PHP. Cada um tem um comando de instalação fixo, executado antes do pre-build, e uma lista de versões que você escolhe no Console. A tabela abaixo reproduz a página Runtimes da documentação, consultada em 06/11/2026; escolha sempre a mesma versão principal que você usa no desenvolvimento.
Alguns detalhes por runtime evitam horas de depuração. No Go, a build é estática, com CGO desativado: pacotes que dependem de CGO, como github.com/mattn/go-sqlite3, compilam mas falham ao iniciar, e a documentação sugere modernc.org/sqlite. No Java, a build usa Eclipse Temurin com Maven 3.9, e a JVM inicia com -XX:MaxRAMPercentage=75, usando até 75% da memória do plano para o heap. No PHP, a aplicação roda no FrankenPHP e o start padrão serve a pasta public/, usada por Laravel, Symfony, Slim e CodeIgniter. No Python, a saída de print() e logging vai sem buffer para os logs, e o ambiente de build já tem compilador C e as bibliotecas do cliente PostgreSQL.
Para os frameworks mais comuns, a documentação traz valores prontos de build e start. Next.js usa npm run build e npx next start -H 0.0.0.0 -p 3000. Express ou Fastify em JavaScript não precisam de build e iniciam com node index.js; em TypeScript, build npm run build e start node dist/index.js. NestJS usa npm run build e node dist/main.js. FastAPI inicia com uvicorn main:app --host 0.0.0.0 --port 8000; Flask, com gunicorn app:app --bind 0.0.0.0:8000. Django usa python manage.py collectstatic --noinput na build e gunicorn config.wsgi --bind 0.0.0.0:8000 no start. Spring Boot com Maven usa mvn -B -DskipTests package e java -jar target/*.jar.
Para migrations, a recomendação é rodar no início do start, quando a aplicação já tem acesso à rede do projeto, e não no pre-build: por exemplo, npx prisma migrate deploy && node dist/main.js, ou alembic upgrade head && uvicorn main:app --host 0.0.0.0 --port 8000. Com várias instâncias, todas executam o start; migrations longas atrasam a subida e, para mudanças grandes, a documentação sugere aplicar antes, de uma máquina com acesso ao banco.
| Runtime | Versões disponíveis | Instalação de dependências | Porta sugerida |
|---|---|---|---|
| Node.js | 20, 22, 24 e 26 | npm ci | 3000 |
| Python | 3.11, 3.12, 3.13 e 3.14 | pip install --no-cache-dir -r requirements.txt (quando o arquivo existe) | 8000 |
| Bun | 1.2, 1.3 e 1.4 | bun install --frozen-lockfile | 3000 |
| Go | 1.25, 1.26 e 1.27 (padrão 1.27) | Sem etapa separada; módulos baixados pela build | 8080 |
| Java | 17, 21 e 25, todas LTS (padrão 21) | Sem etapa separada; Maven ou Gradle wrapper na build | 8080 |
| PHP | 8.3, 8.4 e 8.5 (padrão 8.4) | composer install --no-dev --optimize-autoloader (quando há composer.json) | 8080 |
Variáveis de ambiente na build e na execução
As variáveis do projeto ficam disponíveis em todas as etapas: instalação de dependências, pre-build, build e execução. É isso que permite a frameworks como Vite e Next.js embutirem valores públicos no código do navegador com VITE_* e NEXT_PUBLIC_*. O efeito colateral é importante: tudo o que a build embute fica visível para quem abre a aplicação, então esses prefixos servem para valores públicos, como a URL de uma API, nunca para senhas ou chaves privadas.
Salvar uma variável reinicia as instâncias, mas não refaz a build. Para variáveis lidas em tempo de execução, como DATABASE_URL, isso basta. Para variáveis embutidas na build, o novo valor só aparece depois de uma nova publicação: escolha Novo build em Logs de build ou envie um commit. Esse é um dos motivos mais comuns de "mudei a variável e nada aconteceu" em projetos Vite e Next.js.
A DATABASE_URL não é injetada automaticamente em projetos HTTP. Copie os dados de conexão do banco gerenciado no Console e cadastre a variável no projeto da aplicação; ao rotacionar a senha do banco, atualize todas as aplicações que o usam. A plataforma injeta uma variável própria, ZENIFRA_INSTANCE_VERSION, com a versão publicada que está atendendo a instância. Como a build não recebe o histórico Git nem o comando git, use essa variável quando a aplicação precisar mostrar a versão em logs ou diagnósticos.
| Item | Limite documentado |
|---|---|
| Variáveis por projeto | 50 |
| Tamanho do nome | até 120 caracteres |
| Tamanho do valor | até 32.760 caracteres |
| Formato do nome | começa com letra, _, - ou .; depois, letras sem acento, números, _, - e ., sem espaços |
| Onde configurar | Console (criação ou Editar projeto), CLI (zenifra project env add/update/remove) ou API (PATCH /project/:id/envs) |
Quando usar um Dockerfile próprio
No fluxo por repositório Git, a build usa um ambiente gerado pela Zenifra para o runtime escolhido, e um Dockerfile existente no repositório é ignorado. Se você precisa controlar a imagem (pacotes de sistema específicos, outra linguagem, um servidor web configurado à mão), o caminho é construir a imagem no seu CI e criar o projeto com origem Imagem Docker. A regra prática da documentação: Node.js, Python, Bun, Go, Java ou PHP começam pelo Repositório Git; .NET, Ruby, Rust ou sites servidos por NGINX vão por Imagem OCI.
A imagem precisa de um processo HTTP de longa duração, escutando em 0.0.0.0, na mesma porta do campo Porta, com configuração por variáveis de ambiente. Use tags versionadas, como 1.4.2 ou o SHA do commit, e evite latest: além de previsibilidade, isso facilita o rollback. Em Macs com Apple Silicon, construa com --platform linux/amd64; sem isso, o Docker gera uma imagem ARM que não inicia e aparece como exec format error.
Os comandos de publicação documentados usam o GitHub Container Registry como exemplo. Depois do push, crie o projeto com Origem do Projeto em Imagem Docker, informe o endereço da imagem e, se ela for privada, configure as credenciais do registry. Para automatizar build, push e atualização da imagem a cada mudança, a Zenifra mantém uma GitHub Action oficial, que também cria Ambientes de Preview para projetos com imagem.
echo $GITHUB_TOKEN | docker login ghcr.io -u SEU_USUARIO --password-stdin
docker build --platform linux/amd64 -t ghcr.io/sua-org/minha-api:1.0.0 .
docker push ghcr.io/sua-org/minha-api:1.0.0
# Teste antes
docker run --rm -p 8080:8080 -e PORT=8080 ghcr.io/sua-org/minha-api:1.0.0
curl http://localhost:8080/healthAtualização automática por branch, tag ou release
Cada projeto usa uma única forma de atualização por vez, e a publicação manual continua disponível em todas elas. No Console, Automático por branch vem selecionado ao criar um projeto GitHub. Nos modos Por Tag e Por Release, o padrão é comparado com o nome completo da tag, diferencia maiúsculas de minúsculas, aceita de 1 a 255 caracteres e só tem dois curingas: * (qualquer sequência) e ? (um caractere). Assim, v* corresponde a v1.2.0, mas classes como v[12].* não são aceitas. Atualizar ou remover uma tag existente não inicia publicação.
Para mudar a forma depois, abra o projeto, expanda Repositório Git, escolha Selecionar ou trocar repositório, defina o Modo de deploy e, em Por Tag ou Por Release, o Padrão da tag; depois clique em Salvar repositório. Trocar só o modo não inicia uma build; trocar o repositório ou a branch inicia uma nova build na hora. No Forgejo, a mesma troca pode ser feita pela CLI com zenifra project source deploy-settings set --project <project-id> --mode <manual|branch|tag|release>.
O botão Novo build, em Logs de build, deixa escolher O que publicar: uma Branch (com a opção de fixar um SHA exato do commit), uma Tag específica, mesmo fora do padrão, ou a Versão mais recente do padrão, disponível nos modos Por Tag e Por Release. A escolha vale só para aquele deploy. Só a build mais recente de um projeto é publicada: quando uma nova começa, as anteriores ainda não terminadas aparecem como Substituído, o que não é falha e não altera a aplicação no ar.
Os eventos do GitHub chegam pelo GitHub App Zenifra, com assinatura obrigatória, corpo de até 100 KB e até 300 eventos por minuto por instalação; o excedente recebe 429. Uma entrega recusada não inicia build: publique com Novo build ou com um novo push. Se o app for desinstalado e reinstalado, os projetos da instalação anterior deixam de receber atualizações automáticas até você usar Reconectar repositório.
git tag -a v1.0.0 -m "Release v1.0.0"
git push forgejo v1.0.0| Forma de atualização | O que inicia uma nova publicação |
|---|---|
| Manual | Ação no Console ou POST /v1/project/:id/github/deploy; mudanças no repositório não publicam |
| Automático por branch | Um push na branch selecionada |
| Por Tag | Criação de uma tag que corresponda ao padrão (ex.: v*) |
| Por Release | Publicação de uma release que não seja rascunho, com tag no padrão; pré-releases só se habilitadas |
No Forgejo, o push da tag para o remoto é obrigatório: git tag -a v1.0.0 -m "Release v1.0.0" seguido de git push forgejo v1.0.0. Criar a tag só na cópia local não publica nada.
Logs de build, cache e erros comuns
Os Logs de build, na página do projeto, mostram a lista de builds recentes, o status de cada uma e cada comando na ordem em que roda, no formato $ comando seguido da saída: a instalação (por exemplo, $ npm ci), o pre-build e a build. Quando um comando falha, a saída aparece no log com uma mensagem final indicando a causa identificada. O modal atualiza em tempo real durante a build, e o histórico guarda até 30 builds por projeto, por até 30 dias, o que vencer primeiro.
A primeira build instala tudo; as seguintes reaproveitam etapas que não mudaram. A instalação só é refeita quando os arquivos de dependências mudam, pre-build e build são refeitos quando o código do Diretório raiz muda, e alterar uma variável refaz todas as etapas na próxima build. Uma nova build do mesmo commit com as mesmas variáveis termina em poucos segundos. O cache é de cada projeto e não é compartilhado.
A tabela abaixo reúne os erros documentados com causa e correção. Dois merecem destaque. O primeiro é o lockfile: o Node.js usa npm ci, que exige package-lock.json válido e sincronizado com o package.json, na pasta do Diretório raiz. Projetos com pnpm ou Yarn precisam também de um package-lock.json npm compatível, ou devem publicar por Imagem OCI. O segundo é o histórico Git: a build recebe só os arquivos do commit, sem histórico e sem o comando git, então scripts que chamam git log ou git describe falham com spawnSync git ENOENT.
| Erro nos Logs de build | Causa | Como corrigir |
|---|---|---|
| package-lock.json ausente ou inutilizável | Lockfile fora do Git ou fora do Diretório raiz | Gere com npm, confirme no Git ao lado do package.json e crie uma nova build |
| package-lock.json fora de sincronia | Dependências mudaram sem atualizar o lockfile | Rode npm install, confirme o lockfile, valide com npm ci e crie uma nova build |
| O diretório raiz configurado não existe no repositório. | Pasta inexistente na branch publicada | Corrija o Diretório raiz em Repositório Git e salve (isso inicia uma build) |
| spawnSync git ENOENT ou git: not found | Script de build consulta o histórico Git | Gere a informação antes do commit ou use ZENIFRA_INSTANCE_VERSION |
| VITE_* ou NEXT_PUBLIC_* ausente ou antigo | Variável salva sem nova build | Escolha Novo build em Logs de build |
| O bun.lock está fora de sincronia com o package.json | Lockfile do Bun desatualizado | Rode bun install, confirme o bun.lock e crie uma nova build |
| Um pacote do requirements.txt não existe para Linux ou na versão pedida | Pacote exclusivo do Windows, como pywin32 | Marque com ; sys_platform == "win32" |
| O Composer não conseguiu resolver as dependências | Versão do PHP, nome de pacote ou composer.lock incompatível | Valide composer install localmente com a mesma versão do PHP |
| Acesso ao repositório GitHub rejeitado | Vínculo com o repositório expirado ou removido | Use Reconectar repositório no projeto e tente uma nova build |
Se a build passa e a aplicação não responde, os suspeitos são outros: porta diferente da configurada, servidor escutando em localhost, variável ausente ou erro de inicialização visível nos logs da aplicação. Para voltar a uma versão estável, use Novo build com o SHA exato do commit, ou zenifra deploy --project <project-id> --commit-sha <sha>; no modo Por Tag, crie uma tag nova apontando para o commit bom.
Preciso de um Dockerfile para publicar pelo GitHub?
Não. No caminho por Repositório Git, a Zenifra gera o ambiente de build para o runtime escolhido, e um Dockerfile no repositório é ignorado. Basta ter os arquivos de dependências do runtime (package.json e package-lock.json, requirements.txt, go.mod, pom.xml ou composer.json) e os comandos certos.
O Dockerfile entra quando você escolhe publicar por Imagem OCI: para linguagens fora dos seis runtimes, para controlar pacotes de sistema ou para reaproveitar uma imagem que o seu CI já gera. A documentação traz Dockerfiles prontos para Go, Spring Boot, Laravel e ASP.NET Core.
Posso usar pnpm ou Yarn no runtime Node.js?
Só se o repositório também tiver um package-lock.json npm compatível. A instalação no runtime Node.js é sempre npm ci, e a Zenifra não converte lockfiles nem workspaces de pnpm ou Yarn.
Quando não for possível manter esse lockfile, publique uma Imagem OCI construída pelo seu próprio processo. Outra opção para projetos JavaScript e TypeScript é o runtime Bun, que instala com bun install --frozen-lockfile e usa o bun.lock.
O deploy manual continua disponível com o modo automático ligado?
Sim. Em qualquer forma de atualização, o Novo build em Logs de build continua disponível, e você escolhe se publica uma branch, uma tag ou a versão mais recente do padrão. A escolha vale só para aquele deploy e não muda o modo do projeto.
Isso é útil para republicar depois de mudar uma variável usada na build, para refazer uma entrega de evento recusada ou para voltar a um commit estável fixando o SHA exato.
Como publico uma API e um frontend do mesmo monorepo?
Crie um projeto para cada pasta, cada um com o seu Diretório raiz, por exemplo apps/api e apps/web. Cada projeto tem runtime, comandos, porta, variáveis e plano próprios, e só o conteúdo da pasta configurada entra na build.
Os arquivos de dependências precisam estar dentro de cada pasta: um package-lock.json só na raiz do monorepo não serve para um projeto com Diretório raiz em apps/api. Salvar um novo Diretório raiz inicia uma nova build.
A Zenifra publica a partir do GitLab ou do Bitbucket?
Hoje, as integrações nativas de repositório são GitHub e Forgejo; a documentação do Forgejo informa que a integração com GitLab não está disponível atualmente. Bitbucket não aparece entre as origens documentadas.
Para código em outros provedores, o caminho documentado é construir a imagem no seu CI, publicá-la em um registry e criar o projeto com origem Imagem Docker, atualizando a tag a cada versão pela CLI, pela API ou pelo Console.