Deploy

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çãoQuem pode
Conectar a própria conta do GitLabQuem pode criar projetos na organização ou em um time
Conectar um GitLab próprio com tokenPessoa proprietária (owner) da organização
Criar projeto HTTPproject.create em organization:*
Trocar repositório, branch ou Auto-deployproject.source.update em project:<project-id>
Iniciar um Novo buildproject.deploy.trigger em project:<project-id>
Consultar builds e logsproject.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

  1. No Console, abra a página Conta.
  2. No card GitLab, clique em Conectar GitLab.
  3. O GitLab mostra a tela de autorização do aplicativo Zenifra, que pede os escopos api e read_repository. Autorize o acesso.
  4. 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

  1. No Console, clique em Criar projeto e escolha Aplicação HTTP.
  2. 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.
  3. 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.
  4. Escolha a Branch e ative Auto-deploy para publicar a cada push nessa branch.
  5. 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 backend ou apps/api; veja Diretório raiz e monorepos.
  6. 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

FormaO que inicia uma publicação
Auto-deploy ativadoUm push na branch escolhida
Auto-deploy desativadoSomente 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 como MR !<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:

  1. Em Criar projeto, escolha Repositório Git e o provedor GitLab.
  2. Clique em GitLab próprio da instituição? Conectar com token.
  3. 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.
  4. 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:

  1. Na página Conta, clique em Conectar GitLab.
  2. 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.
  3. 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

Nessa página