> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sincronização com GitHub

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

> [!NOTE]
>
> Este recurso foi desenvolvido por [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) e modificado por [yu-i-i/overleaf-cep](https://github.com/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.

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-36.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=fd5305cbb4ea8505b5eab6f41f90a57c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-39.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=1d8103102915872ba94119bb00fa58e0)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-35.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=18c0d0917b5c3768593a608a53b6c19c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-40.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=7ebf71a5528a1b22e1e2c7f17a71b49a)

### Configurar a sincronização com GitHub

> [!WARNING]
>
> Você precisa habilitar o [git-bridge](https://ayakaleaf-pro.mintlify.site/pt/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md) antes de usar a sincronização com GitHub.
>
> ```dotenv title="config/overleaf.rc" theme={null}
> GIT_BRIDGE_ENABLED=true
> ```

Acesse as [configurações de desenvolvedor](https://github.com/settings/developers) 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.

```dotenv title="config/variables.env" wrap theme={null}
# 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
```

> [!WARNING]
>
> 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.

> [!WARNING]
>
> `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.

> [!WARNING]
>
> 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

> [!NOTE]
>
> 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.

```dotenv title="config/variables.env" wrap theme={null}
# 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` |

> [!WARNING]
>
> * 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.

> [!NOTE]
>
> 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`.

> [!CAUTION]
>
> 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

> [accordion] 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**.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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`.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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](https://ayakaleaf-pro.mintlify.site/pt/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md)) e recrie o contêiner. O Toolkit já define esse valor; verifique se o `docker-compose.override.yml` não o sobrescreve.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.