Deploy a partir do Forgejo

Use uma conexão Forgejo para criar e publicar uma aplicação a partir de um repositório Git, inclusive em uma instância hospedada pela sua organização. A conexão pertence à organização; você escolhe o repositório ao criar cada projeto.

Antes de começar

Tenha o endereço HTTPS da instância Forgejo, com certificado TLS válido e confiável. A instância também precisa estar acessível para a conexão da sua organização; abrir o endereço no navegador não confirma esse acesso.
Tenha uma conta com acesso ao repositório e crie um token pessoal com o menor escopo necessário. Para leitura da origem e deploy manual, use read:repository. Para publicar automaticamente por eventos, use write:repository e uma conta que possa administrar os hooks do repositório.
Anote o caminho completo no formato equipe/aplicacao. A integração não lista nem descobre repositórios: o caminho deve ser informado no Console.
Para automação, a instância Forgejo precisa alcançar por HTTPS o endereço de hook fornecido pela Zenifra. A conexão da Zenifra com o Forgejo e a entrega de eventos pelo Forgejo são requisitos separados.

O escopo write:repository não torna a conta administradora do repositório. Além disso, tokens Forgejo no modo Specific repositories não podem executar operações administrativas, mesmo que a pessoa proprietária do token normalmente possa fazê-las. Como hooks exigem administração do repositório, use uma identidade dedicada com acesso apenas aos repositórios necessários e permissão de administração neles. Ao criar o token, escolha a opção de acesso All (public, private, and limited) e inclua write:repository; não use uma conta administradora da instância. Para uma conexão somente de leitura, um token Specific repositories pode ser limitado aos repositórios selecionados e usar read:repository. Consulte a documentação oficial do Forgejo 16.0 sobre escopos de token e permissões e webhooks de repositório.

Criar o projeto e conectar o Forgejo

No Console, abra Projetos e escolha Novo projeto.
Selecione Aplicação HTTP, defina o plano e preencha as informações do projeto.
Abra Configurações avançadas. Em Origem do Projeto, escolha Repositório Git; em Provedor Git, escolha Forgejo.
Selecione uma conexão Forgejo já disponível para a organização. Se ainda não houver uma, uma pessoa proprietária (owner) da organização pode criá-la no mesmo formulário; outros membros usam apenas as conexões existentes. Para criar a conexão: informe o Endereço da instância, o Nome da conexão, o Caminho do repositório (equipe/aplicacao), o Usuário e o Token de acesso, e escolha Conectar repositório. Não inclua o domínio no caminho nem coloque o token em URLs ou comandos Git.

Captura real do Console com dados ilustrativos; o campo do token está vazio. A imagem mostra o formulário antes da conexão ser confirmada.
Escolha uma branch inicial existente, como main, e a forma de publicação para as atualizações.
Escolha o runtime e sua versão. Informe os comandos de preparação, build e inicialização adequados ao repositório. Se a aplicação estiver em uma subpasta (monorepo), informe-a em Diretório raiz, por exemplo backend ou apps/api; o padrão . usa a raiz do repositório. Veja Diretório raiz e monorepos.
Crie o projeto. A primeira build começa com a criação e usa a branch inicial selecionada.

Depois da criação, abra a build mais recente no Console. Confirme que ela terminou com sucesso, confira o SHA do commit de origem e compare-o com o commit esperado. Por exemplo, rode git rev-parse main para a branch main ou git rev-parse 'v1.0.0^{commit}' para a tag. Quando a build estiver pronta, abra o endereço da aplicação e valide o fluxo principal.

Publicar atualizações

Uma ação manual continua disponível em qualquer forma de publicação. Os modos automáticos usam eventos e hooks do repositório; escolha apenas um deles.

Forma	O que inicia uma publicação
Manual	Uma ação pelo Console ou pela CLI. Você pode publicar a branch escolhida ou um commit específico.
Automático por branch	Um push para a branch selecionada, como `main`.
Por Tag	Um push de tag cujo nome corresponda ao padrão configurado, como `v*`.
Por Release	A publicação de uma release do Forgejo ligada a uma tag que corresponda ao padrão. Rascunhos não são publicados; pré-releases são ignoradas por padrão e podem ser incluídas na configuração do modo.

No terminal, considere que o remoto forgejo aponta para o repositório da instância. O push da branch selecionada inicia uma publicação no modo Automático por branch:

git push forgejo main

No modo Por Tag, crie e envie uma tag para o commit que deve ser publicado. Enviar a tag ao Forgejo é necessário; criá-la somente na sua cópia local não inicia uma publicação:

git tag -a v1.0.0 -m "Release v1.0.0"
git push forgejo v1.0.0

No modo Por Release, envie a tag e depois abra o repositório no Forgejo. Entre em Releases, escolha New Release, selecione a tag v1.0.0, preencha título e notas e publique. Salvar como rascunho não publica a release nem inicia uma build. Uma pré-release é uma release publicada e marcada como pré-release, não um rascunho; ela inicia build somente se a opção de incluir pré-releases estiver habilitada. O Forgejo descreve tags e releases como recursos distintos: a tag pertence ao Git, enquanto a release acrescenta notas e arquivos associados a essa tag.

Os padrões dos modos Por Tag e Por Release são comparados ao nome completo da tag, diferenciam maiúsculas de minúsculas e aceitam de 1 a 255 caracteres. Os únicos curingas são *, para qualquer sequência, e ?, para um caractere; formatos como classes entre colchetes não são aceitos.

Alterar a configuração depois da criação

Na página do projeto, a seção Repositório Git mostra o repositório, a branch e o modo atual. Em Selecionar ou trocar repositório, você pode mudar a conexão, o repositório, a branch e o Modo de deploy; em Comandos de build, ajuste runtime, versão, comandos e Diretório raiz. Assim como os comandos, um novo diretório raiz vale a partir da próxima build. Pela CLI, use zenifra project source deploy-settings set --project <project-id> --mode <manual|branch|tag|release>.

Automação pela CLI e pela API

Para uma publicação manual pela CLI, use os comandos documentados para iniciar a build da branch e acompanhar o resultado:

zenifra deploy --project <project-id> --branch main
zenifra deploy watch --project <project-id> --build <build-id>

Na API de criação de projeto HTTP, a origem fica em config.source e deve ser enviada junto com config.build. Para publicação manual, não habilite auto_deploy e omita version_deploy. Para branch, use auto_deploy: true e omita version_deploy. Para Tag ou Release, mantenha auto_deploy: false e habilite version_deploy, escolhendo o evento e o padrão. Por exemplo, esta parte de config.source configura publicação por Release:

{
  "connection_id": "connection-id",
  "repository_id": "repository-id-from-connection",
  "branch": "main",
  "auto_deploy": false,
  "version_deploy": {
    "enabled": true,
    "event": "release",
    "tag_pattern": "v*",
    "include_prereleases": false
  }
}

Não habilite auto_deploy: true junto com version_deploy.enabled: true; os modos automáticos são mutuamente exclusivos. Consulte a referência de conexões Git para o corpo completo e os campos públicos da API. A integração CLI/GitHub permanece documentada em sua página própria.

Ambientes de Preview por pull request

Projetos com origem Forgejo podem criar Ambientes de Preview automaticamente para pull requests. 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 Forgejo e escolha a Branch de destino dos previews. Como o fluxo depende de eventos do repositório, a conexão precisa do escopo write:repository e de uma conta que administre os hooks.

Pull requests do próprio repositório com destino à branch escolhida criam ou atualizam o preview pr-<number> nos eventos de abertura, reabertura, sincronização e edição; o fechamento remove o preview. Pull requests de forks e para outras branches não participam do fluxo.

Limitações atuais

A integração Forgejo não oferece descoberta de repositórios, origem SSH, submódulos ou Git LFS, e não cria previews para pull requests de forks. Uma integração GitLab também não está disponível atualmente. Esses limites não alteram a integração GitHub existente; consulte o guia de deploy pelo GitHub para as opções específicas dessa conexão.

O runtime, a versão e os comandos de build precisam ser compatíveis com o repositório. Consulte Runtimes para os requisitos de Node.js, Python e Bun.

Dúvidas frequentes

A conexão foi validada, mas o projeto não consegue ler o repositório. O que conferir?

Confirme o caminho equipe/aplicacao, o acesso da conta e o escopo read:repository. Se a instância não for pública, confirme também que ela está acessível para a conexão da organização e que o certificado HTTPS é confiável.

O push foi aceito, mas nenhuma build começou. Por quê?

Confirme que o projeto está no modo Automático por branch e acompanha a mesma branch que recebeu o push. Para qualquer publicação automática, confira se a conta pode administrar hooks, se o token tem write:repository e se o Forgejo conseguiu entregar o evento. Consulte o estado e o histórico de entregas do hook no Forgejo. Um PAT em Specific repositories não administra hooks.

Enviei uma tag ou criei uma release, mas não houve publicação.

Para o modo Por Tag, confirme que enviou a tag ao remoto Forgejo e que o nome corresponde exatamente ao padrão, incluindo maiúsculas e minúsculas. Para o modo Por Release, confirme que escolheu esse modo, publicou a release em vez de salvá-la como rascunho e habilitou pré-releases se a release estiver marcada como pré-release.

A build terminou, mas a aplicação não funciona.

Compare o SHA exibido na build com o commit da branch ou tag, revise os logs da instalação e do build e confirme os comandos de inicialização e o runtime. A página de Runtimes detalha os requisitos disponíveis.