Implantação via GitHub

Use um repositório GitHub como origem do projeto quando quiser publicar a aplicação a partir do código-fonte e do fluxo de build configurado na criação.

Esta página descreve a integração GitHub e seus recursos específicos. Para configurar outro provedor Git, consulte Deploy a partir do Forgejo.

Permissões necessárias

Ação	Scope mínimo
Criar projeto HTTP	`project.create` em `organization:*`
Listar repositórios e branches GitHub ao criar o projeto	`project.source.update` em `project:*`
Configurar repositório, forma de atualização ou comandos GitHub	`project.source.update` em `project:<project-id>`
Disparar deploy manual	`project.deploy.trigger` em `project:<project-id>`
Consultar builds e logs	`project.logs.read` em `project:<project-id>`

owner tem acesso completo. assistant, member e API Keys precisam dos grants correspondentes.

Pré-requisito

Antes de selecionar um repositório, faça estas duas etapas obrigatórias:

uma pessoa proprietária (owner) da organização conecta a conta GitHub à organização na Zenifra
instale o GitHub App Zenifra

Guia detalhado:

Como conectar sua conta GitHub à Zenifra

Nota: O GitHub App pode ser instalado em conta pessoal ou organização. Em organizações, a instalação pode depender de aprovação administrativa.

Passos

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.
Selecione o repositório, a branch, o runtime e os comandos necessários. Se a aplicação estiver em uma subpasta do repositório, preencha Diretório raiz; veja Diretório raiz e monorepos.
Escolha uma das quatro formas de atualização do projeto.
Clique em Criar Projeto.

A primeira build inicia durante a criação do projeto, usando a branch selecionada. Depois dela, a forma de atualização escolhida define quais eventos iniciam novas publicações.

Formas de atualização do GitHub

Cada projeto usa uma única forma de atualização por vez. A publicação manual continua disponível em todas elas.

Forma	O que inicia uma atualização
Manual	Uma ação manual no Console ou uma chamada a `POST /v1/project/:id/github/deploy`. Alterações no repositório não iniciam atualizações.
Automático por branch	Um push na branch selecionada.
Por Tag	A criação de uma tag que corresponda ao padrão configurado. Atualizar ou remover uma tag existente não inicia uma publicação.
Por Release	A publicação de uma release que não seja rascunho e cuja tag corresponda ao padrão. Pré-releases ficam desativadas por padrão e podem ser incluídas nas configurações.

No Console, Automático por branch é a forma selecionada inicialmente ao criar um projeto GitHub. Você pode escolher outra antes de criar o projeto ou alterar a configuração depois.

Nos modos Por Tag e Por Release, o padrão é comparado com o nome completo da tag, diferencia maiúsculas de minúsculas e aceita de 1 a 255 caracteres. Os únicos curingas são *, que corresponde a qualquer sequência de caracteres, e ?, que corresponde a um caractere. O padrão v* corresponde a tags como v1.2.0; sintaxes de glob com classes ou alternativas, como v[12].*, não são aceitas. O padrão * corresponde a qualquer nome de tag.

Alterar a forma de atualização

Você pode alterar a forma de atualização depois da criação do projeto. No Console, abra o projeto, localize o card Deploy pelo GitHub e escolha Editar configuração. Também é possível atualizar a configuração pela API; consulte Builds GitHub para o endpoint. A alteração não troca o repositório nem a branch selecionada para o projeto.

Comandos do projeto

Em projetos GitHub, a Zenifra instala as dependências conforme o runtime selecionado, executa pre-build e build durante a build e usa start quando a aplicação inicia:

pre-build é opcional
build é opcional
start é obrigatório

Essa é a ordem das etapas. Alguns projetos precisam apenas de start, enquanto outros também usam pre-build e build. Todas as etapas rodam dentro do Diretório raiz do projeto.

As variáveis de ambiente do projeto ficam disponíveis no pre-build e no build, o que permite gerar valores como VITE_* e NEXT_PUBLIC_* no código da aplicação. Depois de alterar uma variável usada no build, inicie um Novo build; veja Variáveis durante o build.

Diretório raiz e monorepos

O campo Diretório raiz define a pasta do repositório onde a instalação de dependências, o pre-build, o build e o start são executados. O padrão é ., a raiz do repositório.

Em um monorepo, informe o caminho da pasta da aplicação a partir da raiz do repositório, por exemplo backend ou apps/api. Somente o conteúdo dessa pasta entra na build: arquivos como package.json, package-lock.json e requirements.txt precisam estar dentro dela.

use um caminho relativo dentro do repositório, com / como separador
caminhos absolutos (como /app) e .. não são aceitos
./ no início e / no fim são ignorados: ./backend/ equivale a backend
se a pasta não existir na branch publicada, a build falha com a mensagem "O diretório raiz configurado não existe no repositório."
Diretório raiz não pode apontar para .git: essa pasta não entra na build e é informada como inexistente. A pasta .git também não é incluída na aplicação publicada; se a aplicação precisa do commit atual, use uma variável de ambiente

Você define o Diretório raiz ao criar o projeto e pode alterá-lo depois na tela de editar projeto, junto dos comandos. Assim como ao alterar os comandos, salvar um novo diretório raiz inicia uma nova build.

Para publicar duas aplicações do mesmo repositório, como uma API e um frontend, crie um projeto para cada pasta, cada um com o seu Diretório raiz.

Dependências Node.js

No runtime Node.js, a instalação de dependências executa npm ci antes de qualquer comando pre-build ou build. Para esse fluxo funcionar:

mantenha package.json e um package-lock.json válido juntos na pasta definida em Diretório raiz (por padrão, a raiz do repositório), na branch selecionada
gere e confirme o package-lock.json no Git sempre que alterar as dependências
verifique localmente com a mesma versão do Node.js selecionada no projeto

npm ci
npm run build # somente quando o projeto tiver um script build
npm start

O package-lock.json precisa estar sincronizado com o package.json. Para usar os comandos destes exemplos, defina o script start no package.json. Configure o campo build como npm run build apenas quando o script build existir; caso contrário, deixe o campo vazio.

Por padrão, npm ci instala as dependências declaradas no lockfile. Mantenha TypeScript, bundlers e outras ferramentas exigidas pelo comando build em devDependencies. Se a configuração do projeto definir NODE_ENV=production para a build, essa instalação omite essas dependências; nesse caso, configure pre-build como npm install --include=dev. Esse comando roda depois de npm ci e antes de npm run build, disponibilizando as ferramentas para a build. Ele não pode substituir a instalação inicial por pnpm ou Yarn. Projetos e workspaces que dependem desses gerenciadores precisam fornecer um package-lock.json npm compatível. A Zenifra não converte automaticamente um workspace específico de pnpm ou Yarn; quando não for possível manter esse lockfile, publique uma Imagem OCI construída fora desse fluxo.

devDependencies depois da build

Assim como no Heroku, depois do build a Zenifra remove as devDependencies com npm prune --omit=dev e publica somente o conteúdo do Diretório raiz. A aplicação fica menor e inicia apenas com as dependências de produção, como em uma instalação local com npm ci --omit=dev.

Tudo o que o comando start usa em execução precisa estar em dependencies, inclusive ferramentas chamadas no start, como prisma, drizzle-kit ou knex para migrations
arquivos que o pre-build e o build geram dentro do Diretório raiz, como dist/ ou o client do Prisma em node_modules/.prisma, são publicados. O que esses comandos instalam fora dele, como pacotes do sistema ou npm install -g, não faz parte da aplicação publicada
para manter as devDependencies na aplicação publicada, adicione a variável NPM_CONFIG_PRODUCTION com o valor false em Editar projeto e escolha Novo build em Logs de build. É a mesma variável usada no Heroku

Essa remoção vale para o runtime Node.js. No runtime Bun, as devDependencies continuam instaladas.

Histórico Git durante o build

A build recebe somente os arquivos do commit publicado, sem o histórico do repositório e sem o comando git. Scripts de build que consultam o histórico, por exemplo git log para calcular a data de modificação de páginas no sitemap ou git describe para gerar uma versão, falham nessa etapa.

Gere essas informações antes do commit e versione o resultado no repositório, por exemplo com um workflow que atualiza um arquivo JSON a cada push na branch principal. Para identificar a versão publicada em tempo de execução, use a variável ZENIFRA_INSTANCE_VERSION.

Solução de problemas de build

Consulte Logs de build para identificar a etapa que falhou e siga a orientação correspondente:

Erro	Como corrigir
`package-lock.json` ausente ou inutilizável	Gere um lockfile válido com npm, confirme que ele está no Git ao lado do `package.json`, na branch e no diretório raiz selecionados, e crie uma nova build
`package-lock.json` fora de sincronia	Execute `npm install` para atualizar o lockfile, confirme as mudanças no Git, valide com `npm ci` e crie uma nova build
Acesso ao repositório GitHub rejeitado	A Zenifra tenta renovar automaticamente o vínculo com o mesmo repositório. Se o console ainda indicar que a autorização é necessária, use Reconectar repositório no projeto e tente uma nova build
`O diretório raiz configurado não existe no repositório.`	Confira o Diretório raiz na tela de editar projeto: a pasta precisa existir na branch selecionada, com o caminho a partir da raiz do repositório. Corrija o valor e salve para iniciar uma nova build
Commit indisponível	Crie uma nova build usando o estado atual da branch selecionada. Se o erro persistir para commits atuais, entre em contato com o suporte
`spawnSync git ENOENT` ou `git: not found`	Um script da build está consultando o histórico Git, que não faz parte da build. Veja Histórico Git durante o build
Valor de `VITE_` ou `NEXT_PUBLIC_` ausente ou antigo na aplicação	Confira a variável em Editar projeto e escolha Novo build em Logs de build: salvar a variável reinicia as instâncias, mas não refaz o build
`Cannot find module`, `command not found` ou `npx` baixando um pacote ao iniciar a aplicação	O `start` usa um pacote que está em `devDependencies`, removidas depois da build. Mova o pacote para `dependencies` ou defina `NPM_CONFIG_PRODUCTION=false` e crie uma nova build; veja devDependencies depois da build
Causa não classificada	Revise os Logs de build e os comandos do projeto. A indisponibilidade do diagnóstico adicional não substitui a causa registrada nem exige trocar chaves do projeto

Atualização automática por branch

No modo Automático por branch, cada push na branch selecionada dispara uma nova atualização. A primeira build já foi iniciada na criação; essa forma controla as atualizações causadas por pushes posteriores.

Nos modos Manual, Por Tag e Por Release, um push na branch não inicia uma atualização automática.

Ambientes de Preview

Use Ambientes de Preview para dar a cada pull request uma URL temporária sem substituir o projeto principal. Em projetos com origem GitHub, o caminho nativo cria e atualiza previews sem workflow, API Key ou imagem no repositório. Na seção Ambientes de Preview da página do projeto, escolha Configurar previews, ative Habilitar Ambientes de Preview e Habilitar previews automáticos do GitHub e escolha a Branch de destino dos previews. Essa escolha é independente da forma de atualização principal.

Para pull requests do próprio repositório, os eventos opened, reopened e synchronize criam ou atualizam o preview pr-<number> quando o destino é a branch escolhida; edited reavalia mudanças na branch de destino e closed remove o preview. Pull requests para outra branch e pull requests de forks não participam do fluxo nativo. Pull requests abertos antes da ativação não são importados até um próximo evento relevante. O preview usa o runtime e os comandos já configurados no projeto, mantendo a versão da aplicação principal separada.

Os previews automáticos dependem da permissão de pull requests do GitHub App Zenifra. Se a instalação ainda não aprovou essa permissão, nenhum preview é criado; veja Permissão do GitHub App.

Se uma Action já gerencia a chave pr-<number> para o mesmo projeto e PR, o fluxo nativo não assume nem sobrescreve esse preview: o run nativo fica bloqueado. Escolha um dos fluxos para essa chave.

Projetos com origem em imagem OCI não usam o fluxo nativo: neles, os previews são criados pela GitHub Action com uma imagem pronta. Veja o workflow recomendado para pull requests.

O que permanece fixo depois da criação

Em projetos com origem GitHub, estes campos ficam definidos na criação e não ficam disponíveis para edição depois:

origem do projeto
branch
runtime
versão do runtime

Depois da criação, você também pode alterar a forma de atualização. Os comandos pre-build, build e start e o Diretório raiz continuam editáveis.

Logs de Build

Depois que o projeto é criado, acompanhe cada publicação pela seção Logs de build da página do projeto no console.

Esse histórico mostra:

lista de builds recentes
status de cada build
saída detalhada de instalação de dependências
saída de pre-build, quando existir
saída de build, quando existir

Cada entrada detalhada vem da fonte event e mantém a etapa e a ordem da build. Quando uma build só tem o diagnóstico final disponível, a API retorna uma entrada de fonte summary: ela resume o resultado, mas não substitui eventos detalhados que não foram registrados.

Os logs públicos de build são filtrados para priorizar a saída útil do projeto.

O modal de logs atualiza em tempo real enquanto a build está em execução.

Retenção do histórico

O histórico de builds é retido por até:

30 builds por projeto
30 dias de idade

O que vencer primeiro define a remoção dos registros mais antigos.

URL

Cada projeto público recebe uma URL em *.clients.zenifra.com. Use sempre a URL retornada na criação ou na consulta do projeto como fonte de verdade. A partir do plano Premium, o nome do subdomínio pode ser personalizado.