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.

Em projetos que mostram a seção Repositório Git na página do projeto, a forma de atualização fica no mesmo formulário do repositório. Escolha Selecionar ou trocar repositório, selecione o repositório e escolha o Modo de deploy; em Por Tag ou Por Release, informe o Padrão da tag. Depois clique em Salvar repositório. Salvar não inicia uma build: a próxima publicação vem do evento configurado ou de um Novo build. Ao salvar apenas outra branch no mesmo repositório, o modo Por Tag ou Por Release já configurado é mantido.

Novo build nos modos Por Tag e Por Release

Nos modos Por Tag e Por Release, o Novo build em Logs de build não usa a branch: ele publica a versão mais recente que corresponde ao padrão configurado.

Por Release: a release publicada mais recente que não seja rascunho e cuja tag corresponda ao padrão. Pré-releases entram somente quando estiverem habilitadas.
Por Tag: a tag mais recente, pela data do commit, que corresponda ao padrão.

Nesses modos, os campos de branch e de SHA do commit não aparecem. Se nenhuma versão publicada corresponder ao padrão, o Console mostra "Nenhuma versão publicada corresponde ao padrão" e nenhuma build é criada; publique uma release ou uma tag e tente de novo. Pela API, um pedido com branch ou commit_sha nesses modos é recusado.

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. O runtime atual não remove devDependencies depois dessa etapa. 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.

Tempo de build e cache

A primeira build de um projeto instala todas as dependências e executa todos os comandos. As builds seguintes reaproveitam as etapas cujos arquivos e configurações não mudaram:

a instalação de dependências é refeita somente quando package.json, package-lock.json (ou os arquivos de dependências do runtime) mudam
pre-build e build são refeitos quando o código do Diretório raiz muda
alterar uma variável de ambiente refaz todas as etapas na próxima build, porque as variáveis ficam disponíveis no pre-build e no build
uma nova build do mesmo commit, com as mesmas variáveis, termina em poucos segundos

O cache pertence a cada projeto e não é compartilhado entre projetos. A Zenifra não grava os valores das variáveis na aplicação publicada nem no cache; fazem parte do resultado somente os valores que o próprio build escreve nos arquivos, como VITE_* e NEXT_PUBLIC_*.

Quando um push altera apenas o código, as dependências instaladas são reaproveitadas como estão: elas não são instaladas nem publicadas de novo, o que deixa a build e a atualização mais rápidas.

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
Causa não classificada	Revise a saída do comando que falhou nos Logs de build e os comandos 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
cada comando do projeto, na ordem em que roda, como $ comando seguido da saída dele: a instalação de dependências (por exemplo $ npm ci), o pre-build e o build, quando existirem
mensagens de andamento, como o commit usado, o início da build e a publicação

Quando uma etapa não muda desde a build anterior, ela é reaproveitada: o comando continua aparecendo no log (por exemplo $ npm ci ou $ npm run build), seguido de uma linha indicando o reaproveitamento. Quando um comando falha, a saída dele aparece no log, seguida de uma mensagem final com a causa identificada.

Os logs mostram somente a saída dos comandos do projeto e as mensagens de andamento; detalhes internos da plataforma nunca aparecem.

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

Builds substituídas

Só a build mais recente de um projeto é publicada. Quando uma nova build começa (por um push, uma tag, uma release ou um Novo build), as builds anteriores do mesmo projeto que ainda não terminaram aparecem como Substituído:

se ainda estavam na fila, nem chegam a rodar, e a nova build começa mais cedo;
se já estavam rodando, terminam, mas o resultado não é publicado.

Uma build substituída não é uma falha e não altera a aplicação 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.