Sincronização com GitHub

Permita que os usuários sincronizem seus projetos com repositórios do GitHub ou do GitHub Enterprise.

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

​

Configurar a sincronização com GitHub

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Acesse as configurações de desenvolvedor para criar seu aplicativo OAuth do GitHub e copie seu CLIENT_ID e SECRET.

Observação: ao criar o OAuth App, informe ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback em Authorization callback URL. O Ayakaleaf Pro monta o mesmo endereço a partir de OVERLEAF_SITE_URL, então não há nada a definir para ele em config/variables.env.

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 GitHub access token.
# How to generate: `openssl rand -hex 32`
GITHUB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Github Sync Settings
GITHUB_SYNC_ENABLED=true
GITHUB_SYNC_CLIENT_ID=
GITHUB_SYNC_CLIENT_SECRET=

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

Antes de configurar a URL de callback OAuth do GitHub, certifique-se de que OVERLEAF_SITE_URL esteja definido corretamente.

Se você estiver em uma região com acesso restrito à rede, talvez precise configurar um proxy para acessar o GitHub. Defina a seguinte variável de ambiente: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Certifique-se de que o uso de um proxy esteja em conformidade com as leis e regulamentações locais.

GITHUB_SYNC_PROXY_URL deve ser um proxy de encaminhamento HTTP/HTTPS padrão (por exemplo, a porta HTTP do Clash). Espelhos de download do GitHub, como gh-proxy.org, não são suportados.

Não use 127.0.0.1 como host do proxy. Se o proxy estiver em execução no servidor host, use o endereço IP da LAN do servidor (como 192.168.1.xx) e certifique-se de que o proxy esteja configurado para aceitar conexões de dispositivos da rede local.

​

GitHub Enterprise

O suporte ao GitHub Enterprise foi introduzido na v6.3.1 e posteriores. Versões anteriores se conectam apenas ao github.com, e as variáveis abaixo não têm efeito.

Por padrão, a sincronização com GitHub se conecta ao github.com. Para usar o GitHub Enterprise Server (auto-hospedado) ou o GitHub Enterprise Cloud com residência de dados (GHE.com), defina GITHUB_SYNC_URL como o endereço web da sua instância, aquele com o qual você abre os repositórios no navegador.

config/variables.env

# GitHub Enterprise Server
GITHUB_SYNC_URL=https://github.example.com

# or GitHub Enterprise Cloud with data residency
# GITHUB_SYNC_URL=https://octocorp.ghe.com

Os endpoints das APIs REST e GraphQL são derivados de GITHUB_SYNC_URL da mesma forma que o GitHub CLI faz:

GITHUB_SYNC_URL	API REST	API GraphQL
https://github.com (padrão)	https://api.github.com	https://api.github.com/graphql
https://SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com/graphql
https://HOST (qualquer outro)	https://HOST/api/v3	https://HOST/api/graphql

Defina os endpoints da API apenas quando a sua instância os disponibilizar em outro lugar, por exemplo, atrás de um gateway de API:

Variável	Padrão
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Derivado de GITHUB_SYNC_URL, veja a tabela acima
GITHUB_SYNC_GRAPHQL_URL	Derivado de GITHUB_SYNC_API_URL quando definido (/api/v3 se torna /api/graphql; caso contrário, /graphql é acrescentado); senão, de GITHUB_SYNC_URL

• Crie o aplicativo OAuth na sua instância enterprise (Settings → Developer settings → OAuth Apps); um aplicativo do github.com não funciona nela. A URL de callback é a mesma: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL é apenas o endereço web. Não o defina como um endereço de API, como https://api.github.com ou https://HOST/api/v3, e não adicione um caminho de organização.
• Os três endereços devem apontar para a mesma instância do GitHub.

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

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

​

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 GitHub. 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 GitHub	O proprietário do projeto
Importar um repositório do GitHub 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 GitHub usando a conta do GitHub do usuário que sincroniza; portanto, cada colaborador que sincroniza vincula sua própria conta do GitHub 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 GitHub no projeto.

​

Q&A

Como vinculo um projeto ao GitHub e o sincronizo?

Resposta: No editor, abra Integrations e clique em GitHub. Se a sua conta do GitHub ainda não estiver vinculada, clique primeiro em Link to your GitHub account. Em Export Project to GitHub, insira um nome de repositório, escolha Private em Repository visibility e clique em Create a GitHub repository.

Depois disso, o mesmo cartão abre Sync with GitHub, que lista os novos commits no GitHub. Clique em Sync para fazer commit das suas alterações do Overleaf no branch padrão e trazer as alterações do GitHub para o projeto. A sincronização funciona nos dois sentidos, mas só é executada quando alguém clica em Sync; não há sincronização agendada. Quando os dois lados foram alterados, o Overleaf faz o merge por meio de um branch temporário chamado overleaf-YYYY-MM-DD-HHMMSS. Se esse merge tiver um conflito, faça você mesmo o merge do branch no GitHub e, em seguida, clique em I have manually merged. Continue.

Posso fazer force push no branch padrão?

Resposta: Não recomendamos. O Overleaf detecta um force push, emite um aviso e assume o branch reescrito, mesclando as alterações feitas no Overleaf desde a última sincronização. Para evitar surpresas, proteja o branch padrão contra force pushes nas configurações do repositório.

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

Resposta: Por favor, não faça isso. O Overleaf continua sincronizando com o branch ao qual o projeto foi vinculado. 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 GitHub mostra “Something wrong with GitHub request”

Resposta: Essa mensagem significa que o servidor não conseguiu alcançar o GitHub, por exemplo por causa de um problema de rede, DNS, TLS ou proxy. Execute bin/logs web para ver o erro completo. Se o servidor precisar de um proxy para alcançar o GitHub, defina GITHUB_SYNC_PROXY_URL.

Devo desativar “Expire user access tokens” no GitHub OAuth App?

Resposta: Sim. A sincronização com GitHub não renova tokens expirados. Com tokens que expiram habilitados, os usuários precisam conectar o GitHub novamente sempre que o token expirar.

Minha instância precisa estar acessível pela internet?

Resposta: Não. A vinculação de uma conta passa pelo navegador do usuário, então o endereço de callback do OAuth só precisa abrir no navegador do usuário. O servidor só precisa alcançar o GitHub; se precisar de um proxy para isso, defina GITHUB_SYNC_PROXY_URL. O GitHub nunca chama a sua instância: um projeto só é sincronizado quando um usuário o sincroniza no editor.

A vinculação da minha conta do GitHub falha ou me faz voltar sem vincular

Resposta: Verifique estes itens, nesta ordem:

• Abra o Overleaf exatamente no endereço definido em OVERLEAF_SITE_URL. O GitHub redireciona você de volta para ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, e o seu login só existe no endereço a partir do qual você começou; portanto, outro host, IP ou porta termina na página de login ou em “Restricted, sorry you don’t have permission to load this page”.
• A Authorization callback URL do OAuth App deve ser ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, com o mesmo esquema, host e porta.
• Uma página de erro com Failed to obtain access token from Git server significa que o GitHub não retornou um token: verifique GITHUB_SYNC_CLIENT_ID e GITHUB_SYNC_CLIENT_SECRET e se o servidor consegue alcançar o GitHub. Execute bin/logs web para ver o erro completo.

Depois de alterar config/variables.env, execute bin/up para recriar os contêineres.

A importação de um repositório falha com “EmptyZipFileError: empty_zip_file” ou “unzip failed”

Resposta: O Overleaf importa o arquivo zip do commit mais recente no branch padrão do repositório, e esse erro significa que o arquivo não contém nenhum arquivo que o Overleaf possa importar. Verifique o branch padrão no GitHub:

• Ele contém os arquivos do projeto, e não apenas arquivos que o Overleaf ignora na importação: dotfiles como .gitignore e .gitmodules (.latexmkrc é mantido) e arquivos de compilação como *.aux, *.log, *.bbl, *.synctex.gz, *.doc e *.docx.
• Os arquivos não estão apenas dentro de submódulos do Git. O arquivo do GitHub deixa os submódulos como pastas vazias.
• Os arquivos esperados estão no branch padrão, e não em outro branch. A importação sempre usa o branch padrão.

A importação de um repositório falha com “connect ECONNREFUSED” para “sharelatex:3054”

Resposta: V1_HISTORY_URL está definida como http://sharelatex:3054, um valor indicado por versões mais antigas desta documentação. A porta 3054 é o serviço project-history, que só escuta dentro do contêiner, enquanto V1_HISTORY_URL deve apontar para o history-v1. O Overleaf salva todos os arquivos binários (imagens, PDFs) do repositório importado no history-v1, então a importação falha; o upload desse tipo de arquivo no editor falha da mesma forma. No seu docker-compose.yml, defina V1_HISTORY_URL: "http://sharelatex:3100/api" no serviço sharelatex (consulte Integração com Git) e recrie o contêiner. O Toolkit já define esse valor; verifique se o docker-compose.override.yml não o sobrescreve.