Deploy a partir do GitLab
Use um repositório do GitLab como origem de uma aplicação HTTP. Cada pessoa conecta a própria conta do gitlab.com à Zenifra, escolhe o repositório em uma lista e publica a aplicação a cada push na branch. Para um GitLab próprio da instituição (self-managed), a pessoa proprietária da organização conecta a instância com um token.
Permissões necessárias
| Ação | Quem pode |
|---|---|
| Conectar a própria conta do GitLab | Quem pode criar projetos na organização ou em um time |
| Conectar um GitLab próprio com token | Pessoa proprietária (owner) da organização |
| Criar projeto HTTP | project.create em organization:* |
| Trocar repositório, branch ou Auto-deploy | project.source.update em project:<project-id> |
| Iniciar um Novo build | 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.
Conectar a sua conta do GitLab
- No Console, abra a página Conta.
- No card GitLab, clique em Conectar GitLab.
- O GitLab mostra a tela de autorização do aplicativo Zenifra, que pede os escopos
apieread_repository. Autorize o acesso. - Você volta para a página Conta, e o card passa a mostrar Conectado como com o seu usuário do GitLab.
O escopo read_repository permite ler o código de cada build. O escopo api é necessário para listar os seus repositórios, criar no projeto do GitLab o webhook que avisa a Zenifra de cada push e de cada merge request e comentar nos merge requests.
A conexão é sua: só você usa os seus repositórios por ela, mesmo que outras pessoas da organização também conectem o GitLab. A pessoa proprietária vê em Conexões de provedores Git que a conexão existe, mas não pode usá-la, substituí-la ou revogá-la. A conexão vale para a organização ativa; em outra organização, conecte o GitLab de novo.
Conectar GitLab funciona com contas do gitlab.com. Para um GitLab hospedado pela instituição, veja GitLab próprio da instituição.
Criar o projeto
- No Console, clique em Criar projeto e escolha Aplicação HTTP.
- Em Origem e porta, no campo Origem do Projeto, escolha Repositório Git e, em Provedor Git, escolha GitLab. Se você ainda não conectou a sua conta, o formulário mostra o botão Conectar GitLab.
- Em Repositório, escolha um dos seus repositórios. Use Buscar repositório para filtrar a lista e Carregar mais repositórios para ver os próximos. A lista mostra os projetos em que você tem o papel Maintainer ou superior, inclusive os de subgrupos, como
grupo/subgrupo/aplicacao. - Escolha a Branch e ative Auto-deploy para publicar a cada push nessa branch.
- Escolha o runtime, a versão e os comandos. Se a aplicação estiver em uma subpasta do repositório (monorepo), preencha Diretório raiz, por exemplo
backendouapps/api; veja Diretório raiz e monorepos. - Clique em Criar Projeto. A primeira build começa na criação e usa a branch escolhida.
O papel Maintainer é exigido porque o GitLab só permite criar webhooks a partir dele. Acompanhe a build em Logs de build na página do projeto: o histórico mostra o status de cada build, a saída de cada comando e o commit publicado. Os detalhes de comandos, dependências por runtime e cache valem para todos os provedores Git e estão em Implantação via GitHub.
Publicar atualizações
| Forma | O que inicia uma publicação |
|---|---|
| Auto-deploy ativado | Um push na branch escolhida |
| Auto-deploy desativado | Somente um Novo build no Console |
Com Auto-deploy ativado, a Zenifra cria no projeto do GitLab o webhook que avisa cada push. Pushes em outras branches, tags e branches apagadas não iniciam build.
Para publicar manualmente, abra Logs de build e clique em Novo build. Ele publica a branch configurada no projeto; em SHA exato do commit (opcional) você fixa um commit específico, informando o SHA completo de 40 caracteres. Para publicar outra branch, troque a branch na seção Repositório Git.
Projetos GitLab não têm os modos Por Tag e Por Release: a publicação por tag ou release existe apenas em projetos GitHub e Forgejo.
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 se o Auto-deploy está ativo. Em Selecionar ou trocar repositório, escolha outro repositório, outra branch ou mude o Auto-deploy e clique em Salvar repositório. Trocar o repositório ou a branch inicia uma nova build. Em Comandos de build, ajuste runtime, versão, comandos e Diretório raiz.
Previews por merge request
Projetos GitLab em planos pagos podem criar Ambientes de Preview automaticamente para merge requests. O plano Free (legado) da Zenifra não oferece previews.
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 GitLab e escolha a Branch de destino dos previews. Essa branch define quais merge requests criam previews e não altera a branch da aplicação principal.
Para merge requests do próprio projeto com destino à branch escolhida:
- abrir ou reabrir o merge request cria o preview
pr-<número>, que o Console mostra comoMR !<número>; - um novo commit no merge request atualiza o preview;
- editar o merge request, por exemplo trocando a branch de destino, faz a Zenifra reavaliar o preview;
- fechar ou fazer o merge encerra o preview;
- merge requests de forks e com destino a outras branches não criam preview;
- merge requests abertos antes da ativação entram no fluxo no próximo evento relevante.
Comentário no merge request
A Zenifra mantém um único comentário em cada merge request e o edita a cada mudança, em vez de criar comentários novos:
- quando o preview fica no ar, o comentário mostra a URL e o tempo de vida (TTL) do preview;
- se a build do preview falhar antes da primeira publicação, o comentário pede para ver o log do build no Console; o próximo push tenta de novo;
- quando o preview é encerrado, o comentário mostra a data e a hora do encerramento no horário de Brasília (UTC-3).
O texto sai em português e em inglês. O comentário é publicado com a conta do GitLab de quem conectou o GitLab usado pelo projeto.
GitLab próprio da instituição
Se a instituição hospeda o próprio GitLab (self-managed), a pessoa proprietária da organização conecta a instância com um token:
- Em Criar projeto, escolha Repositório Git e o provedor GitLab.
- Clique em GitLab próprio da instituição? Conectar com token.
- Preencha Endereço da instância (por exemplo
https://gitlab.suainstituicao.edu.br), Nome da conexão, Caminho do repositório (grupo/aplicacao, sem o domínio) e Token de acesso. - Clique em Conectar repositório.
Use um token pessoal, de grupo ou de projeto com os escopos api e read_repository. Para criar o webhook do Auto-deploy e dos previews, o token precisa do papel Maintainer no projeto. No plano gratuito do gitlab.com só existem tokens pessoais; tokens de grupo e de projeto dependem do plano ou da instalação do GitLab.
A instância precisa responder por HTTPS com um certificado válido e estar acessível para a Zenifra. Para o Auto-deploy e os previews, ela também precisa conseguir entregar webhooks à Zenifra por HTTPS. Nessa conexão a Zenifra não lista repositórios: informe o caminho de cada repositório ao criar o projeto.
A conexão por token pertence à organização: outros membros escolhem a conexão em Conexão ao criar projetos. Para trocar o token ou revogar a conexão, abra Conta > Conexões de provedores Git e use Substituir credencial ou Revogar. Não coloque o token em URLs, comandos Git ou variáveis de ambiente do projeto.
Desconectar ou reconectar o GitLab
Para desconectar, clique em Desconectar no card GitLab da página Conta. A Zenifra remove os webhooks que criou nos seus projetos do GitLab e revoga o acesso. Os projetos criados com essa conexão deixam de receber deploys, e as aplicações que já estão no ar continuam funcionando. Para voltar a publicar depois de desconectar:
- Na página Conta, clique em Conectar GitLab.
- Em cada projeto afetado, abra Repositório Git, use Selecionar ou trocar repositório, escolha o repositório de novo e clique em Salvar repositório.
- Se nenhuma build começar, clique em Novo build em Logs de build.
Se a autorização expirar ou se você revogar o acesso do aplicativo Zenifra nas configurações do GitLab, o card mostra Reconecte o GitLab e as builds falham com a mensagem "O GitLab não autorizou mais o acesso a este repositório. Reconecte o GitLab na página Conta e faça o deploy de novo.". Nesse caso, clique em Reconectar GitLab na página Conta e autorize de novo. A Zenifra reaproveita a mesma conexão, e os projetos voltam a receber deploys sem outra mudança. Para publicar o commit que falhou, clique em Novo build em Logs de build.
Entrega de eventos do GitLab
O webhook criado pela Zenifra no projeto do GitLab entrega pushes e merge requests:
- cada entrega leva o token secreto do webhook; entregas sem o token correto são recusadas com
401. Não altere o token secreto do webhook no GitLab; - o corpo de cada entrega pode ter até 100 KB; entregas maiores são recusadas;
- cada webhook pode entregar até 120 eventos por minuto; o excedente é recusado com
429.
Uma entrega recusada não inicia build. Consulte o histórico de entregas em Settings > Webhooks no projeto do GitLab e publique o commit com um Novo build.
Limitações atuais
- não há publicação por tag ou release em projetos GitLab;
- Conectar GitLab funciona com o gitlab.com; um GitLab próprio usa a conexão por token;
- merge requests de forks não criam previews;
- origem SSH, submódulos e Git LFS não são suportados.
Dúvidas frequentes
O meu repositório não aparece na lista. O que conferir?
Confirme que você tem o papel Maintainer ou superior no projeto do GitLab e que a conta conectada é a mesma que tem esse acesso. Use Buscar repositório ou Carregar mais repositórios quando houver muitos projetos.
O push foi aceito, mas nenhuma build começou. Por quê?
Confirme que o Auto-deploy está ativado e que o push foi feito na branch configurada. Depois, confira em Settings > Webhooks do projeto no GitLab se a entrega chegou à Zenifra. O GitLab desativa um webhook que falha várias vezes seguidas; nesse caso, reative-o no GitLab.
Por que o comentário no merge request saiu com o meu usuário?
Os comentários de preview usam a conta do GitLab de quem conectou o GitLab usado pelo projeto.
A build falhou com "Reconecte o GitLab". O que fazer?
O GitLab não aceita mais a autorização. Siga os passos de Desconectar ou reconectar o GitLab.
Próximos passos
Última atualização em
Implantação Automática com GitHub Actions
Configure deploy automático na Zenifra com GitHub Actions: build da imagem OCI, envio ao Docker Hub ou AWS ECR e atualização do projeto a cada tag de versão.
Deploy a partir do Forgejo
Deploy pelo Forgejo na Zenifra: conecte a instância com um token, escolha o repositório e publique por branch, tag ou release, com previews por pull request.