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

1. No Console, abra Projetos e escolha Novo projeto.

2. Selecione Aplicação HTTP, defina o plano e preencha as informações do projeto.

3. Abra Configurações avançadas. Em Origem do Projeto, escolha Repositório Git; em Provedor Git, escolha Forgejo.

4. Selecione uma conexão Forgejo já disponível para a organização. Se ainda não houver uma, crie-a no mesmo formulário: 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.

5. Escolha uma branch inicial existente, como main, e a forma de publicação para as atualizações.

6. Escolha o runtime e sua versão. Informe os comandos de preparação, build e inicialização adequados ao repositório.

7. 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.

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 Branch:

git push forgejo main

No modo 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 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 de Tag e 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.

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.

Limitações atuais

A integração Forgejo não oferece descoberta de repositórios, origem SSH, submódulos, Git LFS ou ambientes de prévia por pull request. Uma integração GitLab também não está disponível atualmente. A validação da origem Git rejeita links simbólicos, hard links e arquivos especiais. 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 e Python.

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 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 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 Release, confirme que escolheu a forma Release, 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.

Próximos passos

• Implantação
• Auto-deploy
• CLI de Deploy e Automação
• Conexões Git pela API