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

# GitLab 동기화

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

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

### GitLab 동기화 설정

<Warning>
  GitLab 동기화를 사용하기 전에 먼저 [git-bridge](/ko/on-premises/configuration/overleaf-toolkit/git-integration)를 활성화해야 합니다.

  ```dotenv title="config/overleaf.rc" theme={null}
  GIT_BRIDGE_ENABLED=true
  ```
</Warning>

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 환경 변수 파일에 다음 설정을 추가하세요.

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

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

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

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

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

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

네트워크 접근이 제한된 지역에 있는 경우 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

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

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


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