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

# GitHub 동기화

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

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

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-36.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=fd5305cbb4ea8505b5eab6f41f90a57c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-39.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=1d8103102915872ba94119bb00fa58e0)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-35.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=18c0d0917b5c3768593a608a53b6c19c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-40.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=7ebf71a5528a1b22e1e2c7f17a71b49a)

### GitHub 동기화 설정

> [!WARNING]
>
> GitHub 동기화를 사용하기 전에 먼저 [git-bridge](https://ayakaleaf-pro.mintlify.site/ko/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md)를 활성화해야 합니다.
>
> ```dotenv title="config/overleaf.rc" theme={null}
> GIT_BRIDGE_ENABLED=true
> ```

[개발자 설정](https://github.com/settings/developers)에 방문하여 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 환경 변수 파일에 다음 설정을 추가하세요.

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

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

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

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

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

### GitHub Enterprise

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

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

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

> [!WARNING]
>
> * 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 인스턴스를 가리켜야 합니다.

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

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

### 연결 및 동기화 권한

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

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

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

### Q\&A

> [accordion] 프로젝트를 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**를 클릭하세요.

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

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

> [accordion] GitHub 동기화에 “Something wrong with GitHub request”가 표시됩니다
>
> **답변:** 이 메시지는 네트워크, DNS, TLS 또는 프록시 문제 등으로 서버가 GitHub에 접근할 수 없었다는 의미입니다. `bin/logs web`을 실행하여 전체 오류를 확인하세요. 서버가 GitHub에 접근하는 데 프록시가 필요하다면 `GITHUB_SYNC_PROXY_URL`을 설정하세요.

> [accordion] GitHub OAuth App에서 “Expire user access tokens”를 비활성화해야 하나요?
>
> **답변:** 예. GitHub 동기화는 만료된 토큰을 갱신하지 않습니다. 토큰 만료가 활성화되어 있으면 사용자는 토큰이 만료될 때마다 GitHub를 다시 연결해야 합니다.

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

> [accordion] 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`을 실행하여 컨테이너를 다시 생성하세요.

> [accordion] 저장소 가져오기가 “EmptyZipFileError: empty\_zip\_file” 또는 “unzip failed”로 실패합니다
>
> **답변:** Overleaf는 저장소 기본 브랜치의 최신 커밋 zip 아카이브를 가져오며, 이 오류는 해당 아카이브에 Overleaf가 가져올 수 있는 파일이 없다는 의미입니다. GitHub에서 기본 브랜치를 확인하세요.
>
> * 가져오기 시 Overleaf가 건너뛰는 파일만 있는 것이 아니라 프로젝트 파일이 포함되어 있는지 확인하세요. 건너뛰는 파일에는 `.gitignore`, `.gitmodules` 같은 dotfile(`.latexmkrc`는 유지됨)과 `*.aux`, `*.log`, `*.bbl`, `*.synctex.gz`, `*.doc`, `*.docx` 같은 빌드 파일이 있습니다.
> * 파일이 Git 서브모듈 안에만 있지 않은지 확인하세요. GitHub의 아카이브는 서브모듈을 빈 폴더로 남깁니다.
> * 기대하는 파일이 다른 브랜치가 아닌 기본 브랜치에 있는지 확인하세요. 가져오기는 항상 기본 브랜치를 사용합니다.

> [accordion] 저장소 가져오기가 “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 연동](https://ayakaleaf-pro.mintlify.site/ko/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md) 참조) 컨테이너를 다시 생성하세요. Toolkit은 이미 이 값을 설정하므로 `docker-compose.override.yml`이 이 값을 재정의하지 않는지 확인하세요.


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