Sincronização com GitLab

Este recurso foi desenvolvido por ayaka-notes/ayakaleaf-pro. Ele foi introduzido na v6.4.0 e posteriores. Ainda está em fase beta. Precisamos do seu feedback caso encontre algum problema.

A sincronização com GitLab funciona como a sincronização com GitHub: os usuários vinculam sua conta do GitLab, exportam projetos para novos projetos do GitLab, importam repositórios do GitLab e sincronizam as alterações em ambas as direções. Ela funciona com o GitLab.com e com o GitLab autogerenciado 15.10 ou posterior (Community e Enterprise Edition).

​

Configurar a sincronização com GitLab

Você precisa habilitar o git-bridge antes de usar a sincronização com GitLab.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Crie um aplicativo OAuth na sua instância do GitLab, em User settings → Applications (ou Admin area → Applications para um aplicativo de toda a instância):

• Redirect URI: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
• Confidential: marcado
• Scopes: api

Copie o Application ID e o Secret e, em seguida, adicione as seguintes configurações aos seus arquivos de variáveis de ambiente do Overleaf.

config/variables.env

# used to encrypt the user's GitLab access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITLAB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# GitLab Sync Settings
GITLAB_SYNC_ENABLED=true
GITLAB_SYNC_CLIENT_ID=
GITLAB_SYNC_CLIENT_SECRET=

# Web address of your GitLab, defaults to https://gitlab.com
# GITLAB_SYNC_URL=https://gitlab.example.com

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
# (Optional) GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808

Antes de configurar a URI de redirecionamento OAuth do GitLab, certifique-se de que OVERLEAF_SITE_URL esteja definido corretamente.

Os tokens de acesso do GitLab expiram após duas horas. O Overleaf os renova com o token de atualização que o GitLab emite junto com eles, de modo que os usuários permanecem vinculados até desvincularem ou revogarem o aplicativo no GitLab.

​

GitLab autogerenciado

Defina GITLAB_SYNC_URL como o endereço web da sua instância, aquele com o qual você abre os projetos no navegador. A API REST é derivada dele:

Variável	Padrão
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

Defina GITLAB_SYNC_API_URL apenas quando a sua instância disponibilizar a API em outro lugar, por exemplo, atrás de um gateway de API.

• Crie o aplicativo OAuth na instância definida em GITLAB_SYNC_URL; um aplicativo do gitlab.com não funciona em uma instância autogerenciada.
• GITLAB_SYNC_URL é apenas o endereço web. Não adicione /api/v4 nem um caminho de grupo.

Se a sua instância usar um certificado de uma CA privada, monte o certificado da CA no contêiner e aponte NODE_EXTRA_CA_CERTS para ele, por exemplo, NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitlab-ca.pem.

Contas e projetos vinculados pertencem à instância com a qual foram vinculados. Antes de mudar GITLAB_SYNC_URL para outra instância, peça aos usuários que desvinculem sua conta do GitLab e seus projetos.

Se você estiver em uma região com acesso restrito à rede, talvez precise configurar um proxy para acessar o GitLab. Defina a seguinte variável de ambiente: GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808. Ele deve ser um proxy de encaminhamento HTTP/HTTPS padrão e não deve usar 127.0.0.1.

​

Quem pode vincular e sincronizar

Assim como no Overleaf Cloud, apenas o proprietário do projeto pode vincular um projeto a um repositório do GitLab. Depois de vinculado, todos os colaboradores com acesso de edição podem sincronizá-lo.

Ação	Quem pode fazer
Exportar um projeto para um novo repositório do GitLab	O proprietário do projeto
Importar um repositório do GitLab para um novo projeto	Qualquer usuário, que se torna o proprietário do novo projeto
Fazer pull, push e merge de um projeto vinculado	O proprietário e os colaboradores com acesso de edição
Desvincular um projeto do seu repositório	O proprietário do projeto

• O Overleaf se comunica com o GitLab usando a conta do GitLab do usuário que sincroniza; portanto, cada colaborador que sincroniza vincula sua própria conta do GitLab e precisa ter permissão para fazer push no branch padrão do repositório.
• Colaboradores somente leitura não podem usar a sincronização com GitLab no projeto.

​

Como a sincronização funciona com o GitLab

• Permissões: os usuários precisam ter permissão para fazer push no branch padrão do projeto vinculado. Quando o branch padrão está protegido e o usuário não pode fazer push nele, o Overleaf pede que ele entre em contato com o proprietário do projeto, como acontece com um repositório ao qual ele perdeu o acesso.
• Merge: quando um projeto foi alterado tanto no Overleaf quanto no GitLab, o Overleaf faz commit de suas alterações em um branch temporário chamado overleaf-YYYY-MM-DD-HHMMSS e o mescla por meio de um merge request, porque o GitLab não tem uma API para mesclar branches sem um. Após o merge, o Overleaf exclui o branch temporário e o merge request. Somente administradores e proprietários de projetos podem excluir merge requests no GitLab; portanto, para outros usuários, o merge request mesclado permanece no projeto.
• Regras de merge: o Overleaf nunca contorna as regras de merge do projeto. Quando o merge request tem um conflito, ou precisa de uma aprovação ou de um pipeline bem-sucedido, ele permanece aberto e o Overleaf pede ao usuário que o mescle no GitLab e, em seguida, continue a sincronização.
• Pipelines: commits do Overleaf iniciam pipelines como qualquer outro commit. Se o seu projeto executa pipelines para merge requests e exige que eles sejam bem-sucedidos, os merges do Overleaf aguardam por eles, conforme descrito acima.

​

Q&A

Posso fazer force push no branch padrão?

Resposta: Mantenha os force pushes no branch padrão desativados. Esse é o padrão do GitLab: o branch padrão de um novo projeto é protegido e ninguém pode fazer force push nele. O Overleaf consegue assumir um branch reescrito, mas a sincronização com GitLab foi projetada para um branch padrão cujo histórico apenas cresce.

Posso renomear o branch padrão de um projeto vinculado?

Resposta: Não. O Overleaf continua sincronizando com o branch ao qual o projeto foi vinculado, portanto as sincronizações falham quando esse branch é renomeado ou removido. Para sincronizar com outro branch, desvincule o projeto e, em seguida, importe o repositório para um novo projeto, que usará o branch padrão atual.