> ## 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.

# GitHub Synchronisation

> Let users sync their projects with GitHub or GitHub Enterprise repositories on a Kubernetes deployment.

GitHub Synchronisation runs in the **web** service (the `github-sync` module) of every Ayakaleaf Pro pod. It needs the [Git integration](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/kubernetes/integrations/git-integration.md). Create the OAuth application and read what each setting does in [GitHub Synchronisation](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/overleaf-toolkit/integrations/github-synchronisation.md); this page puts it into Kubernetes.

| | |
| - | - |
| Service | web (`github-sync` module), in every Ayakaleaf Pro pod; read when web starts |
| Pod → GitHub | `https://api.github.com` (REST and GraphQL), or the API of `GITHUB_SYNC_URL`, whenever a user links, imports, exports or syncs |
| Browser → GitHub | `https://github.com/login/oauth/authorize` to link an account, then back to `${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback` |
| GitHub → Overleaf | none: no webhook, the instance does not need to be reachable from GitHub |
| Stored data | the user's GitHub access tokens, encrypted, in MongoDB |
| Periodic jobs | none: syncing happens when a user clicks |

### Configuration

**1. ConfigMap**

```yaml title="30-config.yaml (additions)" theme={null}
  GITHUB_SYNC_ENABLED: "true"
  GITHUB_SYNC_CLIENT_ID: <client ID>
  # GitHub Enterprise: its web address
  # GITHUB_SYNC_URL: https://github.example.com
  # optional: send the module's requests to GitHub through an HTTP proxy
  # GITHUB_SYNC_PROXY_URL: http://proxy.example.com:3128
```

`GIT_BRIDGE_ENABLED: "true"` and the git-bridge StatefulSet from [Git integration](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/kubernetes/integrations/git-integration.md) must be in place: without them the account settings and the editor hide GitHub Synchronisation.

**2. Secret**

```bash theme={null}
kubectl -n overleaf patch secret overleaf-secrets --type merge -p '{"stringData":{
  "GITHUB_SYNC_CLIENT_SECRET":"<client secret>",
  "GITHUB_TOKEN_CIPHER_PASSWORD":"'"$(openssl rand -hex 32)"'"}}'
```

`GITHUB_TOKEN_CIPHER_PASSWORD` encrypts the users' GitHub access tokens in MongoDB. Every replica must use the same value, and changing it later makes every user link GitHub again.

**3. Private CA (optional)**

If your GitHub has a certificate from your own CA, add the CA to the Secret `overleaf-certs` mounted at `/var/lib/overleaf/certs` (see [Certificates and other files](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/kubernetes#certificates-and-other-files)) and set `NODE_EXTRA_CA_CERTS: /var/lib/overleaf/certs/ca.pem` in the ConfigMap.

**4. Apply, restart and check**

```bash theme={null}
kubectl apply -f 30-config.yaml
kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
for p in $(kubectl -n overleaf get pod -l app=overleaf -o name); do   # app=overleaf-ha for several replicas
  kubectl -n overleaf exec "$p" -- curl -sS -o /dev/null -w "$p %{http_code}\n" https://api.github.com
done
```

Any HTTP status means GitHub is reachable from that pod; `000` means it is not.

### Several replicas

Nothing extra beyond the shared `GITHUB_TOKEN_CIPHER_PASSWORD`. A sync takes a lock in Redis, shared with the other Git synchronisations, so two replicas never sync the same project at once.

### Tested on Kubernetes

Against a mock of github.com and its REST and GraphQL APIs (trusted through `NODE_EXTRA_CA_CERTS` from `overleaf-certs`), on Kubernetes 1.37 with one replica and the Git integration on, our end-to-end tests for GitHub Synchronisation pass (31 cases): linking and unlinking the account, revoked tokens, exporting a project into a new private or organization repository, importing a repository (also over the upload limit), pulling and pushing, merges, conflicts and manual merges, deleted and force-pushed branches, binary files, renames and deletions, losing push access, and what owners, editors and viewers may do.


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