Gitea 동기화

이 기능은 ayaka-notes/ayakaleaf-pro에서 개발했습니다. v6.3.2에서 얼리 프리뷰로 도입되었으며 v6.4.0에서 정식 출시될 예정이므로, 구성과 동작이 아직 변경될 수 있습니다. 문제가 있으면 피드백을 보내주세요.

Gitea 동기화는 GitHub 동기화 및 GitLab 동기화와 같은 방식으로 동작합니다. 사용자는 Gitea 계정을 연결하고, 프로젝트를 새 Gitea 저장소로 내보내고, Gitea 저장소를 가져오고, 양방향으로 변경 사항을 동기화할 수 있습니다. gitea.com 또는 자체 인스턴스의 Gitea 1.23 이상에서 동작합니다.

​

Gitea 동기화 설정

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Gitea 인스턴스의 Settings → Applications → Manage OAuth2 applications(인스턴스 전체 애플리케이션의 경우 Site Administration → Integrations → Applications)에서 OAuth2 애플리케이션을 만드세요.

• Application name: 예: Overleaf. 사용자가 애플리케이션을 승인할 때 이 이름이 표시됩니다
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: 체크

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

config/variables.env

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

# Gitea Sync Settings
GITEA_SYNC_ENABLED=true
GITEA_SYNC_CLIENT_ID=
GITEA_SYNC_CLIENT_SECRET=

# Web address of your Gitea (its ROOT_URL), defaults to https://gitea.com
# GITEA_SYNC_URL=https://gitea.example.com

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

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

Overleaf는 사용자가 계정을 연결할 때 동기화에 필요한 모든 권한을 요청하므로, 사용자는 권한이 부족해서 다시 연결해야 하는 일이 없습니다.

스코프	용도
write:repository	저장소와 그 파일(.gitea/workflows 아래의 CI 워크플로 포함), 브랜치 및 풀 리퀘스트
write:user	내보낼 때 사용자의 저장소 생성(Gitea는 POST /user/repos에 이 스코프를 요구함)
write:organization	사용자의 조직 목록 조회 및 내보낼 때 조직의 저장소 생성

Gitea는 사용자가 애플리케이션을 승인할 때 이러한 스코프를 표시하며, 토큰을 해당 스코프로 제한합니다.

Gitea 액세스 토큰은 1시간 후에 만료됩니다([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf는 Gitea가 함께 발급하는 리프레시 토큰으로 액세스 토큰을 갱신하며, Gitea가 리프레시 토큰을 사용 시 소모하는 경우(INVALIDATE_REFRESH_TOKENS = true)에도 마찬가지입니다. 따라서 사용자는 연결을 해제하거나 Gitea에서 애플리케이션을 취소하기 전까지 연결된 상태로 유지됩니다.

​

Gitea 인스턴스

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

변수	기본값
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

하위 경로에서 제공되는 Gitea도 동작합니다. 예: GITEA_SYNC_URL=https://example.com/gitea. 인스턴스가 API를 다른 위치(예: API 게이트웨이 뒤)에서 제공하는 경우에만 GITEA_SYNC_API_URL을 설정하세요.

• OAuth2 애플리케이션은 GITEA_SYNC_URL에 설정한 인스턴스에서 만드세요. 다른 인스턴스에서 만든 애플리케이션은 동작하지 않습니다.
• GITEA_SYNC_URL은 웹 주소만 입력합니다. /api/v1이나 사용자 또는 조직 경로를 추가하지 마세요.
• Overleaf는 Gitea의 파일 API로 커밋하며, 이 API에는 웹 편집기가 필요합니다. [repository.editor]를 활성화된 상태(기본값)로 유지하세요.

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

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

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

​

연결 및 동기화 권한

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

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

• Overleaf는 동기화하는 사용자의 Gitea 계정으로 Gitea와 통신합니다. 따라서 동기화하는 모든 공동 작업자는 자신의 Gitea 계정을 연결해야 하며, 저장소의 기본 브랜치에 push할 수 있는 권한이 있어야 합니다.
• 보기 전용 공동 작업자는 해당 프로젝트에서 Gitea 동기화를 사용할 수 없습니다.
• Overleaf에서 계정 연결을 해제하면 해당 토큰은 삭제됩니다. Gitea에는 토큰을 취소하는 API가 없으므로, 원한다면 Gitea의 _Settings → Applications_에서도 권한 부여를 취소하세요.

​

Gitea와의 동기화 방식

• 권한: 사용자는 연결된 저장소의 기본 브랜치에 push할 수 있는 권한이 있어야 합니다. 브랜치 보호 규칙 때문에 사용자가 push할 수 없는 경우, 접근 권한을 잃은 저장소와 마찬가지로 Overleaf는 프로젝트 소유자에게 문의하도록 안내합니다.
• 병합: 프로젝트가 Overleaf와 Gitea 양쪽에서 변경된 경우, Overleaf는 변경 사항을 overleaf-YYYY-MM-DD-HHMMSS라는 이름의 임시 브랜치에 커밋하고 저장소의 기본 병합 방식으로 풀 리퀘스트를 통해 병합합니다. Gitea에는 풀 리퀘스트 없이 브랜치를 병합하는 API가 없기 때문입니다. 병합 후 Overleaf는 임시 브랜치를 삭제하며, 병합된 풀 리퀘스트는 기록으로 저장소에 남습니다.
• 병합 규칙: Overleaf는 저장소의 브랜치 보호를 절대 우회하지 않습니다. 풀 리퀘스트에 충돌이 있거나 승인 또는 상태 검사 통과가 필요한 경우 풀 리퀘스트는 열린 상태로 유지되며, Overleaf는 사용자에게 Gitea에서 병합한 후 동기화를 계속하도록 안내합니다.
• CI 워크플로: Overleaf는 .gitea/workflows/와 같은 dotfile을 표시하지 않으며, 저장소에 있는 그대로 유지합니다. Overleaf에서 생성된 커밋도 다른 커밋과 마찬가지로 Gitea Actions를 시작합니다.

​

Q&A

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

답변: 브랜치 보호 규칙 등을 사용하여 기본 브랜치에 대한 force push는 비활성화된 상태로 유지하세요. Overleaf는 재작성된 브랜치를 이어받을 수 있지만, Gitea 동기화는 이력이 계속 늘어나기만 하는 기본 브랜치를 전제로 설계되었습니다.

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

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

Gitea 동기화는 Git LFS를 지원하나요?

답변: 아니요. Overleaf 프로젝트는 Git Large File Storage를 지원하지 않습니다. Git LFS로 추적되는 파일은 Overleaf에서 실제 내용이 아닌 LFS 포인터 파일로 나타납니다. 대신 이미지와 PDF를 저장소에 직접 커밋하세요.

SHA-256 저장소에서도 동작하나요?

답변: 아직은 아닙니다. Overleaf는 파일을 SHA-1 ID로 비교하므로, SHA-256 객체 형식으로 만든 저장소에서는 pull할 때마다 변경되지 않은 파일까지 모든 파일을 다시 씁니다. 손실되는 내용은 없지만, 기본 SHA-1 형식을 사용하세요.

Forgejo에서도 동작하나요?

답변: Gitea 동기화는 Gitea만을 대상으로 개발 및 테스트되었습니다.