GitLab 동기화

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

GitLab 동기화는 GitHub 동기화와 같은 방식으로 동작합니다. 사용자는 GitLab 계정을 연결하고, 프로젝트를 새 GitLab 프로젝트로 내보내고, GitLab 저장소를 가져오고, 양방향으로 변경 사항을 동기화할 수 있습니다. GitLab.com 및 GitLab 15.10 이상의 자체 관리형 GitLab(Community Edition 및 Enterprise Edition)에서 동작합니다.

​

GitLab 동기화 설정

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

GitLab 인스턴스의 User settings → Applications(인스턴스 전체 애플리케이션의 경우 Admin area → Applications)에서 OAuth 애플리케이션을 만드세요.

• Redirect URI: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
• Confidential: 체크
• Scopes: api

Application ID와 Secret을 복사한 다음 overleaf 환경 변수 파일에 다음 설정을 추가하세요.

config/variables.env

# used to encrypt the user's GitLab access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITLAB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# GitLab Sync Settings
GITLAB_SYNC_ENABLED=true
GITLAB_SYNC_CLIENT_ID=
GITLAB_SYNC_CLIENT_SECRET=

# Web address of your GitLab, defaults to https://gitlab.com
# GITLAB_SYNC_URL=https://gitlab.example.com

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

GitLab OAuth 리디렉션 URI를 구성하기 전에 OVERLEAF_SITE_URL이 올바르게 설정되어 있는지 확인하세요.

GitLab 액세스 토큰은 2시간 후에 만료됩니다. Overleaf는 GitLab이 함께 발급하는 리프레시 토큰으로 액세스 토큰을 갱신하므로, 사용자는 연결을 해제하거나 GitLab에서 애플리케이션을 취소하기 전까지 연결된 상태로 유지됩니다.

​

자체 관리형 GitLab

GITLAB_SYNC_URL을 인스턴스의 웹 주소, 즉 브라우저에서 프로젝트를 열 때 사용하는 주소로 설정하세요. REST API 주소는 이 값에서 파생됩니다.

변수	기본값
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

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

• OAuth 애플리케이션은 GITLAB_SYNC_URL에 설정한 인스턴스에서 만드세요. gitlab.com에서 만든 애플리케이션은 자체 관리형 인스턴스에서 동작하지 않습니다.
• GITLAB_SYNC_URL은 웹 주소만 입력합니다. /api/v4나 그룹 경로를 추가하지 마세요.

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

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

네트워크 접근이 제한된 지역에 있는 경우 GitLab에 접근하기 위해 프록시를 구성해야 할 수 있습니다. 다음 환경 변수를 설정하세요: GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808. 표준 HTTP/HTTPS 포워드 프록시여야 하며 127.0.0.1을 사용해서는 안 됩니다.

​

연결 및 동기화 권한

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

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

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

​

GitLab과의 동기화 방식

• 권한: 사용자는 연결된 프로젝트의 기본 브랜치에 push할 수 있는 권한이 있어야 합니다. 기본 브랜치가 보호되어 있어 사용자가 push할 수 없는 경우, 접근 권한을 잃은 저장소와 마찬가지로 Overleaf는 프로젝트 소유자에게 문의하도록 안내합니다.
• 병합: 프로젝트가 Overleaf와 GitLab 양쪽에서 변경된 경우, Overleaf는 변경 사항을 overleaf-YYYY-MM-DD-HHMMSS라는 이름의 임시 브랜치에 커밋하고 merge request를 통해 병합합니다. GitLab에는 merge request 없이 브랜치를 병합하는 API가 없기 때문입니다. 병합 후 Overleaf는 임시 브랜치와 merge request를 삭제합니다. GitLab에서는 관리자와 프로젝트 소유자만 merge request를 삭제할 수 있으므로, 다른 사용자의 경우 병합된 merge request가 프로젝트에 남아 있습니다.
• 병합 규칙: Overleaf는 프로젝트의 병합 규칙을 절대 우회하지 않습니다. merge request에 충돌이 있거나 승인 또는 파이프라인 통과가 필요한 경우 merge request는 열린 상태로 유지되며, Overleaf는 사용자에게 GitLab에서 병합한 후 동기화를 계속하도록 안내합니다.
• 파이프라인: Overleaf에서 생성된 커밋도 다른 커밋과 마찬가지로 파이프라인을 시작합니다. 프로젝트에서 merge request에 대해 파이프라인을 실행하고 통과를 요구하는 경우, 위에서 설명한 대로 Overleaf의 병합은 파이프라인 완료를 기다립니다.

​

Q&A

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

답변: 기본 브랜치에 대한 force push는 비활성화된 상태로 유지하세요. 이는 GitLab의 기본 설정입니다. 새 프로젝트의 기본 브랜치는 보호되며 누구도 force push할 수 없습니다. Overleaf는 재작성된 브랜치를 이어받을 수 있지만, GitLab 동기화는 이력이 계속 늘어나기만 하는 기본 브랜치를 전제로 설계되었습니다.

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

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