Implantação via GitHubCopy Anchor Link

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áriasCopy Anchor Link

owner tem acesso completo. assistant, member e API Keys precisam dos grants correspondentes. Quem altera comandos sem project.deploy.trigger salva a mudança, mas nenhum build é iniciado: a resposta indica build_required: true e a mudança chega à aplicação no próximo build.

Pré-requisitoCopy Anchor Link

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.

PassosCopy Anchor Link

1. No console, clique em Criar projeto e escolha Aplicação HTTP.
2. Em Configurações Avançadas, no campo Origem do Projeto, escolha Repositório Git e, em Provedor Git, escolha GitHub.
3. 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.
4. Escolha uma das quatro formas de atualização do projeto.
5. 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 GitHubCopy Anchor Link

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

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çãoCopy Anchor Link

Você pode alterar a forma de atualização depois da criação do projeto. No Console, abra o projeto e expanda a seção Repositório Git; 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. Trocar só o modo de deploy não inicia uma build: a próxima publicação vem do evento configurado ou de um Novo build. Trocar o repositório ou a branch inicia uma nova build na hora. Ao salvar apenas outra branch no mesmo repositório, o modo Por Tag ou Por Release já configurado é mantido. Também é possível atualizar a configuração pela API; consulte Builds GitHub para o endpoint.

Novo build nos modos Por Tag e Por ReleaseCopy Anchor Link

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 projetoCopy Anchor Link

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 monoreposCopy Anchor Link

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 seção Repositório Git, junto dos comandos; veja editar projeto. 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 buildCopy Anchor Link

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 buildCopy Anchor Link

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

Atualização automática por branchCopy Anchor Link

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.

Entrega de eventos do GitHubCopy Anchor Link

Os eventos de push, tag, release e pull request chegam à Zenifra pelo GitHub App Zenifra:

• toda entrega precisa ter uma assinatura válida do GitHub; entregas sem assinatura ou com assinatura inválida são recusadas;
• o corpo de cada entrega pode ter até 100 KB; entregas maiores são recusadas;
• cada instalação do GitHub App (ou, sem instalação, cada repositório) pode entregar até 300 eventos por minuto; o excedente é recusado com 429 (Too many webhook deliveries).

Uma entrega recusada não inicia build. Para publicar o commit, use Novo build em Logs de build ou envie um novo push.

Um evento só atualiza projetos conectados pela mesma instalação do GitHub App que o entregou. Se o GitHub App for desinstalado e instalado de novo, os projetos conectados pela instalação anterior deixam de receber atualizações automáticas: reconecte o repositório no projeto e, até lá, use Novo build. Antes de um build manual, a Zenifra confirma que o repositório continua acessível pela instalação; se ele foi removido da instalação, o build é recusado.

Ambientes de PreviewCopy Anchor Link

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çãoCopy Anchor Link

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 BuildCopy Anchor Link

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ídasCopy Anchor Link

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óricoCopy Anchor Link

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.

URLCopy Anchor Link

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.

Próximos passosCopy Anchor Link

• Dependências Node.js
• Automático por branch
• Portas e health checks
• Rollback