Sincronização com Gitea

Este recurso foi desenvolvido por ayaka-notes/ayakaleaf-pro. Ele foi introduzido na v6.3.2 como prévia antecipada e será lançado oficialmente na v6.4.0, portanto sua configuração e seu comportamento ainda podem mudar. Precisamos do seu feedback caso encontre algum problema.

A sincronização com Gitea funciona como a sincronização com GitHub e a sincronização com GitLab: os usuários vinculam sua conta do Gitea, exportam projetos para novos repositórios do Gitea, importam repositórios do Gitea e sincronizam as alterações em ambas as direções. Ela funciona com o Gitea 1.23 ou posterior, no gitea.com ou na sua própria instância.

​

Configurar a sincronização com Gitea

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Crie um aplicativo OAuth2 na sua instância do Gitea, em Settings → Applications → Manage OAuth2 applications (ou Site Administration → Integrations → Applications para um aplicativo de toda a instância):

• Application name: por exemplo, Overleaf; os usuários o veem ao autorizá-lo
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: marcado

Copie o Client ID e o Client 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 Gitea access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITEA_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Gitea Sync Settings
GITEA_SYNC_ENABLED=true
GITEA_SYNC_CLIENT_ID=
GITEA_SYNC_CLIENT_SECRET=

# Web address of your Gitea (its ROOT_URL), defaults to https://gitea.com
# GITEA_SYNC_URL=https://gitea.example.com

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

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

O Overleaf solicita tudo de que uma sincronização precisa quando o usuário vincula a conta, de modo que os usuários nunca precisam vincular novamente por falta de uma permissão:

Escopo	Usado para
write:repository	Repositórios, seus arquivos (incluindo os workflows de CI em .gitea/workflows), branches e pull requests
write:user	Criar um repositório do usuário ao exportar (o Gitea o exige em POST /user/repos)
write:organization	Listar as organizações do usuário e criar um repositório de uma delas ao exportar

O Gitea mostra esses escopos quando o usuário autoriza o aplicativo e limita o token a eles.

Os tokens de acesso do Gitea expiram após uma hora ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). O Overleaf os renova com o token de atualização que o Gitea emite junto com eles, inclusive quando o Gitea invalida os tokens de atualização após o uso (INVALIDATE_REFRESH_TOKENS = true), de modo que os usuários permanecem vinculados até desvincularem ou revogarem o aplicativo no Gitea.

​

Sua instância do Gitea

Defina GITEA_SYNC_URL como o endereço web da sua instância, o seu ROOT_URL, aquele com o qual você abre os repositórios no navegador. A API REST é derivada dele:

Variável	Padrão
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

Um Gitea disponibilizado em um subcaminho também funciona, por exemplo, GITEA_SYNC_URL=https://example.com/gitea. Defina GITEA_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 OAuth2 na instância definida em GITEA_SYNC_URL; um aplicativo de outra instância não funciona.
• GITEA_SYNC_URL é apenas o endereço web. Não adicione /api/v1 nem um caminho de usuário ou de organização.
• O Overleaf faz commits com a API de arquivos do Gitea, que precisa do editor web: mantenha [repository.editor] habilitado (o padrão).

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/gitea-ca.pem.

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

Se você estiver em uma região com acesso restrito à rede, talvez precise configurar um proxy para acessar o Gitea. Defina a seguinte variável de ambiente: GITEA_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 Gitea. 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 Gitea	O proprietário do projeto
Importar um repositório do Gitea 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 Gitea usando a conta do Gitea do usuário que sincroniza; portanto, cada colaborador que sincroniza vincula sua própria conta do Gitea 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 Gitea no projeto.
• Desvincular a conta no Overleaf descarta o token dela; o Gitea não tem uma API para revogá-lo, então, se quiser, revogue também a autorização em Settings → Applications no Gitea.

​

Como a sincronização funciona com o Gitea

• Permissões: os usuários precisam ter permissão para fazer push no branch padrão do repositório vinculado. Quando uma regra de proteção de branch não permite que o usuário faça 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 Gitea, 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 pull request com o estilo de merge padrão do repositório, porque o Gitea não tem uma API para mesclar branches sem um. Após o merge, o Overleaf exclui o branch temporário; o pull request mesclado permanece no repositório como registro.
• Regras de merge: o Overleaf nunca contorna a proteção de branches do repositório. Quando o pull request tem um conflito, ou precisa de aprovações ou de verificações de status bem-sucedidas, ele permanece aberto e o Overleaf pede ao usuário que o mescle no Gitea e, em seguida, continue a sincronização.
• Workflows de CI: o Overleaf não mostra dotfiles como .gitea/workflows/ e os mantém como estão no repositório. Commits do Overleaf iniciam o Gitea Actions como qualquer outro commit.

​

Q&A

Posso fazer force push no branch padrão?

Resposta: Mantenha os force pushes no branch padrão desativados, por exemplo, com uma regra de proteção de branch. O Overleaf consegue assumir um branch reescrito, mas a sincronização com Gitea 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.

A sincronização com Gitea oferece suporte ao Git LFS?

Resposta: Não. Os projetos do Overleaf não oferecem suporte ao Git Large File Storage. Os arquivos rastreados pelo Git LFS aparecem no Overleaf como arquivos de ponteiro do LFS, e não com o seu conteúdo. Em vez disso, faça commit de imagens e PDFs diretamente no repositório.

Funciona com repositórios SHA-256?

Resposta: Ainda não. O Overleaf compara os arquivos pelos seus IDs SHA-1; portanto, em um repositório criado com o formato de objeto SHA-256, cada pull reescreve todos os arquivos, mesmo os inalterados. Nada é perdido, mas use o formato SHA-1 padrão.

Funciona com o Forgejo?

Resposta: A sincronização com Gitea foi desenvolvida e testada apenas com o Gitea.