GitHub 동기화

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

이 기능은 ayaka-notes/ayakaleaf-pro에서 개발하고 yu-i-i/overleaf-cep에서 수정했습니다. v6.2.0 이상부터 도입되었으며 아직 베타 상태입니다. 문제가 있으면 피드백을 보내주세요.

​

GitHub 동기화 설정

GitHub 동기화를 사용하기 전에 먼저 git-bridge를 활성화해야 합니다.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

개발자 설정에 방문하여 GitHub OAuth 애플리케이션을 만들고 CLIENT_ID와 SECRET을 복사하세요.

참고: OAuth App을 만들 때 Authorization callback URL에 ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback을 입력하세요. Ayakaleaf Pro는 OVERLEAF_SITE_URL로부터 동일한 주소를 구성하므로 config/variables.env에서 따로 설정할 것은 없습니다.

그런 다음 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

GitHub OAuth 콜백 URL을 구성하기 전에 OVERLEAF_SITE_URL이 올바르게 설정되어 있는지 확인하세요.

네트워크 접근이 제한된 지역에 있는 경우 GitHub에 접근하기 위해 프록시를 구성해야 할 수 있습니다. 다음 환경 변수를 설정하세요: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. 프록시 사용이 현지 법률 및 규정을 준수하는지 확인하세요.

GITHUB_SYNC_PROXY_URL은 표준 HTTP/HTTPS 포워드 프록시(예: Clash의 HTTP 포트)여야 합니다. gh-proxy.org와 같은 GitHub 다운로드 미러는 지원되지 않습니다.

프록시 호스트로 127.0.0.1을 사용하지 마세요. 프록시가 호스트 서버에서 실행 중이라면 서버의 LAN IP 주소(예: 192.168.1.xx)를 사용하고, 프록시가 로컬 네트워크의 기기로부터 연결을 허용하도록 구성되어 있는지 확인하세요.

​

GitHub Enterprise

GitHub Enterprise 지원은 v6.3.1 이상부터 도입되었습니다. 이전 버전은 github.com에만 연결되며 아래 변수는 효과가 없습니다.

기본적으로 GitHub 동기화는 github.com에 연결됩니다. GitHub Enterprise Server(셀프 호스팅) 또는 데이터 레지던시가 적용된 GitHub Enterprise Cloud(GHE.com)를 사용하려면 GITHUB_SYNC_URL을 인스턴스의 웹 주소, 즉 브라우저에서 저장소를 열 때 사용하는 주소로 설정하세요.

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

REST 및 GraphQL API 엔드포인트는 GitHub CLI와 같은 방식으로 GITHUB_SYNC_URL에서 파생됩니다.

GITHUB_SYNC_URL	REST API	GraphQL API
https://github.com (기본값)	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 (그 외)	https://HOST/api/v3	https://HOST/api/graphql

인스턴스가 API 엔드포인트를 다른 위치(예: API 게이트웨이 뒤)에서 제공하는 경우에만 API 엔드포인트를 설정하세요.

변수	기본값
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	GITHUB_SYNC_URL에서 파생됨, 위 표 참조
GITHUB_SYNC_GRAPHQL_URL	GITHUB_SYNC_API_URL이 설정된 경우 이 값에서 파생됨(/api/v3은 /api/graphql로 바뀌고, 그렇지 않으면 /graphql이 추가됨), 그렇지 않으면 GITHUB_SYNC_URL에서 파생됨

• OAuth 애플리케이션은 엔터프라이즈 인스턴스(Settings → Developer settings → OAuth Apps)에서 만드세요. github.com에서 만든 애플리케이션은 해당 인스턴스에서 동작하지 않습니다. 콜백 URL은 동일합니다: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL은 웹 주소만 입력합니다. https://api.github.com이나 https://HOST/api/v3 같은 API 주소로 설정하지 말고, 조직 경로도 추가하지 마세요.
• 세 주소는 모두 동일한 GitHub 인스턴스를 가리켜야 합니다.

인스턴스가 사설 CA에서 발급한 인증서를 사용하는 경우 CA 인증서를 컨테이너에 마운트하고 NODE_EXTRA_CA_CERTS가 이를 가리키도록 설정하세요. 예: NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/github-ca.pem.

연결된 계정과 프로젝트는 연결 당시의 인스턴스에 속합니다. GITHUB_SYNC_URL을 다른 인스턴스로 변경하기 전에 사용자에게 GitHub 계정과 프로젝트의 연결을 해제하도록 요청하세요.

​

연결 및 동기화 권한

Overleaf Cloud와 마찬가지로 프로젝트 소유자만 프로젝트를 GitHub 저장소에 연결할 수 있습니다. 연결된 후에는 편집 권한이 있는 모든 공동 작업자가 동기화할 수 있습니다.

작업	수행 가능한 사용자
프로젝트를 새 GitHub 저장소로 내보내기	프로젝트 소유자
GitHub 저장소를 새 프로젝트로 가져오기	모든 사용자(새 프로젝트의 소유자가 됨)
연결된 프로젝트의 pull, push 및 병합	소유자 및 편집 권한이 있는 공동 작업자
프로젝트와 저장소의 연결 해제	프로젝트 소유자

• Overleaf는 동기화하는 사용자의 GitHub 계정으로 GitHub와 통신합니다. 따라서 동기화하는 모든 공동 작업자는 자신의 GitHub 계정을 연결해야 하며, 저장소의 기본 브랜치에 push할 수 있는 권한이 있어야 합니다.
• 보기 전용 공동 작업자는 해당 프로젝트에서 GitHub 동기화를 사용할 수 없습니다.

​

Q&A

프로젝트를 GitHub에 연결하고 동기화하려면 어떻게 하나요?

답변: 편집기에서 Integrations를 열고 GitHub를 클릭하세요. GitHub 계정이 아직 연결되지 않았다면 먼저 Link to your GitHub account를 클릭하세요. Export Project to GitHub에서 저장소 이름을 입력하고 Repository visibility에서 Private을 선택한 다음 Create a GitHub repository를 클릭하세요.

그 후에는 같은 카드에서 Sync with GitHub가 열리며, GitHub의 새 커밋 목록이 표시됩니다. Sync를 클릭하면 Overleaf의 변경 사항이 기본 브랜치에 커밋되고 GitHub의 변경 사항이 프로젝트로 가져와집니다. 동기화는 양방향으로 이루어지지만 누군가 Sync를 클릭할 때만 실행되며, 예약된 동기화는 없습니다. 양쪽 모두 변경된 경우 Overleaf는 overleaf-YYYY-MM-DD-HHMMSS라는 이름의 임시 브랜치를 통해 병합합니다. 이 병합에 충돌이 있으면 GitHub에서 직접 브랜치를 병합한 후 I have manually merged. Continue를 클릭하세요.

기본 브랜치에 force push를 해도 되나요?

답변: 권장하지 않습니다. Overleaf는 force push를 감지하면 경고를 표시하고, 재작성된 브랜치를 이어받아 마지막 동기화 이후 Overleaf에서 변경된 내용을 병합합니다. 예상치 못한 문제를 피하려면 저장소 설정에서 기본 브랜치를 force push로부터 보호하세요.

연결된 프로젝트의 기본 브랜치 이름을 변경할 수 있나요?

답변: 변경하지 마세요. Overleaf는 프로젝트가 연결된 브랜치와 계속 동기화합니다. 다른 브랜치와 동기화하려면 프로젝트의 연결을 해제한 다음, 현재 기본 브랜치를 사용하는 새 프로젝트로 저장소를 가져오세요.

GitHub 동기화에 “Something wrong with GitHub request”가 표시됩니다

답변: 이 메시지는 네트워크, DNS, TLS 또는 프록시 문제 등으로 서버가 GitHub에 접근할 수 없었다는 의미입니다. bin/logs web을 실행하여 전체 오류를 확인하세요. 서버가 GitHub에 접근하는 데 프록시가 필요하다면 GITHUB_SYNC_PROXY_URL을 설정하세요.

GitHub OAuth App에서 “Expire user access tokens”를 비활성화해야 하나요?

답변: 예. GitHub 동기화는 만료된 토큰을 갱신하지 않습니다. 토큰 만료가 활성화되어 있으면 사용자는 토큰이 만료될 때마다 GitHub를 다시 연결해야 합니다.

인스턴스가 인터넷에서 접근 가능해야 하나요?

답변: 아니요. 계정 연결은 사용자의 브라우저를 통해 이루어지므로, OAuth 콜백 주소는 사용자의 브라우저에서만 열리면 됩니다. 서버는 GitHub에만 접근할 수 있으면 되며, 이를 위해 프록시가 필요한 경우 GITHUB_SYNC_PROXY_URL을 설정하세요. GitHub는 인스턴스를 호출하지 않습니다. 프로젝트는 사용자가 편집기에서 동기화할 때만 동기화됩니다.

GitHub 계정 연결이 실패하거나 연결되지 않은 채 되돌아갑니다

답변: 다음을 순서대로 확인하세요.

• OVERLEAF_SITE_URL에 설정된 주소와 정확히 같은 주소로 Overleaf를 여세요. GitHub는 ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback으로 되돌려 보내며, 로그인은 처음 시작한 주소에만 존재하므로 다른 호스트, IP 또는 포트를 사용하면 로그인 페이지나 “Restricted, sorry you don’t have permission to load this page”로 끝납니다.
• OAuth App의 Authorization callback URL은 스킴, 호스트, 포트가 모두 같은 ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback이어야 합니다.
• Failed to obtain access token from Git server가 표시된 오류 페이지는 GitHub가 토큰을 반환하지 않았다는 의미입니다. GITHUB_SYNC_CLIENT_ID와 GITHUB_SYNC_CLIENT_SECRET을 확인하고, 서버가 GitHub에 접근할 수 있는지 확인하세요. 전체 오류를 보려면 bin/logs web을 실행하세요.

config/variables.env를 변경한 후에는 bin/up을 실행하여 컨테이너를 다시 생성하세요.

저장소 가져오기가 “EmptyZipFileError: empty_zip_file” 또는 “unzip failed”로 실패합니다

답변: Overleaf는 저장소 기본 브랜치의 최신 커밋 zip 아카이브를 가져오며, 이 오류는 해당 아카이브에 Overleaf가 가져올 수 있는 파일이 없다는 의미입니다. GitHub에서 기본 브랜치를 확인하세요.

• 가져오기 시 Overleaf가 건너뛰는 파일만 있는 것이 아니라 프로젝트 파일이 포함되어 있는지 확인하세요. 건너뛰는 파일에는 .gitignore, .gitmodules 같은 dotfile(.latexmkrc는 유지됨)과 *.aux, *.log, *.bbl, *.synctex.gz, *.doc, *.docx 같은 빌드 파일이 있습니다.
• 파일이 Git 서브모듈 안에만 있지 않은지 확인하세요. GitHub의 아카이브는 서브모듈을 빈 폴더로 남깁니다.
• 기대하는 파일이 다른 브랜치가 아닌 기본 브랜치에 있는지 확인하세요. 가져오기는 항상 기본 브랜치를 사용합니다.

저장소 가져오기가 “sharelatex:3054”에 대한 “connect ECONNREFUSED”로 실패합니다

답변: V1_HISTORY_URL이 이 문서의 이전 버전에서 안내했던 값인 http://sharelatex:3054로 설정되어 있습니다. 포트 3054는 컨테이너 내부에서만 수신하는 project-history 서비스이지만, V1_HISTORY_URL은 history-v1을 가리켜야 합니다. Overleaf는 가져온 저장소의 모든 바이너리 파일(이미지, PDF)을 history-v1에 저장하므로 가져오기가 실패하며, 편집기에서 이러한 파일을 업로드할 때도 같은 방식으로 실패합니다. docker-compose.yml에서 sharelatex 서비스에 V1_HISTORY_URL: "http://sharelatex:3100/api"를 설정하고(Git 연동 참조) 컨테이너를 다시 생성하세요. Toolkit은 이미 이 값을 설정하므로 docker-compose.override.yml이 이 값을 재정의하지 않는지 확인하세요.