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

# Gitea 동기화

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

Gitea 동기화는 [GitHub 동기화](https://ayakaleaf-pro.mintlify.site/ko/on-premises/configuration/overleaf-toolkit/github-synchronisation.md) 및 [GitLab 동기화](https://ayakaleaf-pro.mintlify.site/ko/on-premises/configuration/overleaf-toolkit/gitlab-synchronisation.md)와 같은 방식으로 동작합니다. 사용자는 Gitea 계정을 연결하고, 프로젝트를 새 Gitea 저장소로 내보내고, Gitea 저장소를 가져오고, 양방향으로 변경 사항을 동기화할 수 있습니다. gitea.com 또는 자체 인스턴스의 Gitea 1.23 이상에서 동작합니다.

### Gitea 동기화 설정

> [!WARNING]
>
> Gitea 동기화를 사용하기 전에 먼저 [git-bridge](https://ayakaleaf-pro.mintlify.site/ko/on-premises/configuration/overleaf-toolkit/git-integration.md)를 활성화해야 합니다.
>
> ```dotenv title="config/overleaf.rc" theme={null}
> 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 환경 변수 파일에 다음 설정을 추가하세요.

```dotenv title="config/variables.env" wrap theme={null}
# 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
```

> [!WARNING]
>
> 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`을 설정하세요.

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

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

> [!CAUTION]
>
> 연결된 계정과 프로젝트는 연결 당시의 인스턴스에 속합니다. `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만을 대상으로 개발 및 테스트되었습니다.


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