GitHub 동기화

Kubernetes 배포에서 사용자가 프로젝트를 GitHub 또는 GitHub Enterprise 저장소와 동기화할 수 있도록 합니다.

GitHub 동기화는 모든 Ayakaleaf Pro 파드의 web 서비스(github-sync 모듈)에서 실행됩니다. Git 연동이 필요합니다. OAuth 애플리케이션을 만드는 방법과 각 설정의 역할은 GitHub 동기화에서 확인하세요. 이 페이지에서는 이를 Kubernetes에 적용하는 방법을 설명합니다.

서비스	web(github-sync 모듈), 모든 Ayakaleaf Pro 파드에 포함; web 시작 시 읽음
파드 → GitHub	사용자가 연결, 가져오기, 내보내기 또는 동기화할 때마다 https://api.github.com(REST 및 GraphQL) 또는 GITHUB_SYNC_URL의 API
브라우저 → GitHub	계정 연결을 위해 https://github.com/login/oauth/authorize로 이동한 뒤 ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback으로 돌아옴
GitHub → Overleaf	없음: webhook이 없으며, 인스턴스가 GitHub에서 접근 가능할 필요가 없음
저장되는 데이터	암호화된 사용자의 GitHub 액세스 토큰, MongoDB에 저장
주기적 작업	없음: 사용자가 클릭할 때 동기화됨

​

구성

1. ConfigMap

   30-config.yaml (additions)

     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"와 Git 연동의 git-bridge StatefulSet이 준비되어 있어야 합니다. 그렇지 않으면 계정 설정과 편집기에서 GitHub 동기화가 숨겨집니다.

2. Secret

   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는 MongoDB에 저장되는 사용자의 GitHub 액세스 토큰을 암호화합니다. 모든 레플리카는 같은 값을 사용해야 하며, 나중에 이 값을 변경하면 모든 사용자가 GitHub를 다시 연결해야 합니다.

3. 사설 CA(선택 사항)

   GitHub가 자체 CA에서 발급한 인증서를 사용하는 경우 /var/lib/overleaf/certs에 마운트되는 Secret overleaf-certs에 CA를 추가하고(인증서 및 기타 파일 참조), ConfigMap에 NODE_EXTRA_CA_CERTS: /var/lib/overleaf/certs/ca.pem을 설정하세요.

4. 적용, 재시작 및 확인

   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
   

   어떤 HTTP 상태 코드든 반환되면 해당 파드에서 GitHub에 접근할 수 있다는 의미이며, 000은 접근할 수 없다는 의미입니다.

​

여러 레플리카

공유되는 GITHUB_TOKEN_CIPHER_PASSWORD 외에는 추가로 필요한 것이 없습니다. 동기화는 다른 Git 동기화와 공유되는 Redis 잠금을 사용하므로 두 레플리카가 같은 프로젝트를 동시에 동기화하는 일은 없습니다.

​

Kubernetes에서의 테스트

github.com과 그 REST 및 GraphQL API의 모의 서버(overleaf-certs의 NODE_EXTRA_CA_CERTS를 통해 신뢰됨)를 대상으로, 레플리카 하나와 Git 연동을 활성화한 Kubernetes 1.37에서 GitHub 동기화에 대한 엔드 투 엔드 테스트가 통과했습니다(31개 케이스). 테스트 항목은 계정 연결 및 연결 해제, 취소된 토큰, 프로젝트를 새 비공개 또는 조직 저장소로 내보내기, 저장소 가져오기(업로드 제한 초과 포함), pull 및 push, 병합, 충돌 및 수동 병합, 삭제되거나 force push된 브랜치, 바이너리 파일, 이름 변경 및 삭제, push 권한 상실, 그리고 소유자, 편집자, 보기 전용 사용자가 할 수 있는 작업입니다.