multica/apps/docs/content/docs/github-integration.ko.mdx

---
title: GitHub 연동
description: pull request를 Multica 이슈에 연결하고 이슈에서 개발 진행 상황을 확인합니다.
---

import { Callout } from "fumadocs-ui/components/callout";

GitHub를 연결하면 Multica가 이슈 번호를 기준으로 pull request를 자동 연결합니다. 이슈 상세 화면에서 PR 상태, 변경 규모, CI 결과, merge conflict를 바로 확인할 수 있습니다.

GitHub 연동은 설치할 때 승인한 저장소만 읽으며 코드, 댓글, status check를 제출하지 않습니다.

자체 배포한 Multica에서는 자체 호스팅 Forgejo, Gitea, GitLab 인스턴스도 동시에 연결해 동일한 PR 자동 연결, merge 시 Done 전환, CI 표시 기능을 사용할 수 있습니다. **설정 → 연동 → Git 코드 호스팅**에서 연결하며 자세한 내용은 [자체 호스팅 Git 코드 호스팅](/vcs-integration)을 참고하세요. Multica Cloud에는 이 메뉴가 없습니다.

## GitHub 연결

워크스페이스 owner 또는 admin이 연결할 수 있습니다.

1. **설정 → GitHub**를 엽니다.
2. GitHub 연동 전체 스위치를 켭니다.
3. **GitHub 연결**을 클릭합니다.
4. GitHub에서 계정 또는 조직을 선택하고 모든 저장소나 지정한 저장소를 승인합니다.
5. 설치가 끝나면 Multica로 돌아옵니다.

연결 상태는 같은 페이지에 표시됩니다. 일반 멤버는 상태를 볼 수 있지만 연결, 연결 해제, 스위치 변경은 할 수 없습니다.

<Callout type="info">
**GitHub 연결**은 Multica가 어느 저장소에서 PR 이벤트를 받을지 결정합니다. **코드 저장소** 설정은 에이전트가 태스크를 실행할 때 선택할 수 있는 저장소를 결정합니다. 용도가 다르므로 각각 설정해야 합니다.
</Callout>

## 기능 스위치

**설정 → GitHub**에는 네 가지 스위치가 있습니다.

| 스위치 | 역할 |
|---|---|
| GitHub 연동 | 전체 스위치입니다. 끄면 아래 세 기능이 작동하지 않지만 GitHub App 연결은 해제되지 않습니다. |
| PR 사이드바 | 이슈 상세 화면에 연결된 pull request를 표시합니다. |
| Co-authored-by | 에이전트가 만든 commit에 `Co-authored-by: multica-agent <[email protected]>`를 추가합니다. |
| PR 자동 연결 | PR의 브랜치 이름, 제목, 본문에서 이슈 번호를 찾습니다. |
| **PR 카드 → CI와 머지 가능 여부** | 연결된 각 PR에 대해 Multica는 인증된 GitHub API 스냅샷을 가져와, 그 **CI 상태**와 **머지 가능 여부**를 카드에 미러링합니다(아래 **PR 카드에 표시되는 것** 참조). |


## PR을 이슈에 연결

가장 간단한 방법은 이슈 번호를 브랜치 이름이나 PR 제목에 넣는 것입니다. 예를 들어 이슈가 `MUL-123`인 경우:

```text
mul-123-fix-login-redirect
```

```text
MUL-123 로그인 후 리디렉션 수정
```

Multica는 대소문자를 구분하지 않으며 현재 워크스페이스의 이슈 접두사만 매칭합니다. 하나의 PR을 여러 이슈에 연결할 수 있습니다.

이슈 번호를 PR 본문에만 쓸 때는 GitHub의 종료 문구를 사용해야 합니다.

```text
Closes MUL-123
Fixes MUL-123
Resolves MUL-123
```

본문의 `Related to MUL-123` 같은 일반 언급은 해당 이슈의 작업 PR로 표시되지 않습니다. Commit message와 PR 댓글도 연결을 트리거하지 않습니다.

## 이슈에서 PR 확인

연결에 성공하면 PR이 이슈 상세 화면의 **Pull requests** 영역에 나타납니다. 각 항목에는 다음 내용이 표시됩니다.

- 저장소, 번호, 제목, 작성자
- `Open`, `Draft`, `Merged`, `Closed` 상태
- 추가 및 삭제한 줄 수와 변경한 파일 수
- CI 상태: 모두 통과(개수 표시), 일부 실패(실패한 check 이름 표시), 일부 진행 중. 설정된 check가 없는 PR에는 이 항목을 표시하지 않으며 "check 없음"을 통과로 간주하지 않습니다.
- merge 가능 여부: merge 가능(GitHub가 merge 상태를 clean으로 보고한 경우만), conflict 있음, blocked, behind

CI 상태와 merge 가능 여부는 Multica가 GitHub API에서 가져온 snapshot이며 서로 독립적입니다. 이미 merge되거나 닫힌 PR에는 두 항목을 더 이상 표시하지 않습니다. GitHub를 일시적으로 사용할 수 없으면 카드가 비워지는 대신 마지막 snapshot을 유지하고 만료된 정보라고 표시합니다.

항목을 클릭하면 GitHub의 PR이 열립니다. **PR 사이드바**를 꺼도 이 영역만 숨겨질 뿐 연결은 해제되지 않습니다.

## PR merge 시 Done 전환 조건

PR이 merge되었다고 이슈가 반드시 완료된 것은 아닙니다. Multica는 다음 조건이 모두 충족될 때만 이슈를 `Done`으로 바꿉니다.

1. merge된 연결 PR이 하나 이상 있고, `Closes MUL-123`처럼 종료 문구 바로 뒤에 번호가 있습니다(`Closes login MUL-123`처럼 중간에 다른 단어가 있으면 적용되지 않음).
2. 해당 이슈에 `Open` 또는 `Draft` 상태인 다른 작업 PR이 없습니다. 본문의 일반 언급은 작업 PR에 포함되지 않습니다.
3. 이슈의 현재 상태가 `done` 또는 `cancelled`가 아닙니다.

따라서 브랜치 이름이나 제목에 `MUL-123`만 넣으면 연결은 되지만 그것만으로 완료를 트리거하지 않습니다. PR을 merge하지 않고 닫아도 이슈가 완료되지 않습니다.

상태 변경은 시스템 작업으로 타임라인에 기록되고 해당 이슈 구독자에게 알림이 전달됩니다.

## 여러 워크스페이스

같은 GitHub App installation을 여러 Multica 워크스페이스에 연결할 수 있습니다. GitHub 이벤트는 각 워크스페이스로 따로 들어가고 각 워크스페이스의 이슈 접두사를 기준으로 매칭됩니다.

예를 들어 PR 하나에서 `MUL-1`과 `ENG-2`를 함께 참조하면 서로 다른 접두사를 사용하는 두 워크스페이스에 각각 연결될 수 있습니다. 워크스페이스는 서로의 이슈를 볼 수 없습니다.

## 연결 해제

**설정 → GitHub**에서 **연결 해제**를 클릭하면 현재 Multica 워크스페이스와 해당 installation의 관계만 제거됩니다. GitHub에서 App을 대신 제거하지는 않습니다. 기존 PR 기록은 유지되고 새 이벤트만 해당 워크스페이스에 들어오지 않습니다.

GitHub 측의 저장소 승인을 취소하려면 개인 또는 조직의 GitHub App installations 페이지에서 App을 제거하거나 저장소 범위를 조정해야 합니다. App을 제거하면 해당 installation에 연결된 모든 Multica 워크스페이스가 이벤트 수신을 중지합니다.

## 자체 호스팅 설정

Multica Cloud에서는 이 절차가 필요 없습니다. 자체 호스팅 환경에서는 자신의 GitHub App을 먼저 만들어야 합니다.

### 1. GitHub App 만들기

GitHub의 **Developer settings → GitHub Apps**에서 App을 만들고 다음 값을 입력합니다.

| 필드 | 값 |
|---|---|
| Homepage URL | Multica 프런트엔드 주소. 예: `https://multica.example.com` |
| Callback URL | 비워 둠 |
| Setup URL | `https://<api-host>/api/github/setup`, **Redirect on update** 활성화 |
| Webhook URL | `https://<api-host>/api/webhooks/github` |
| Webhook secret | 장기 보관할 임의 문자열 |

Repository permissions:

| 권한 | 수준 |
|---|---|
| Metadata | Read-only |
| Pull requests | Read-only |
| Checks | Read-only. CI 상태 표시에 사용 |
| Commit statuses | Read-only. legacy status 형식의 CI 집계에 사용 |

다음 이벤트를 구독합니다.

- **Pull request**
- CI와 merge 가능 여부 새로 고침을 트리거할 **Check suite**, **Check run**, **Status**

Multica에서 CI를 표시할 필요가 없다면 Checks 및 Commit statuses 권한을 부여하거나 관련 이벤트를 구독하지 않아도 됩니다.

<Callout type="warning">
여기에는 OAuth Client secret이 아니라 **Webhook secret**이 필요합니다. 양쪽에 입력한 Webhook secret이 다르면 GitHub delivery가 `401 invalid signature`를 반환합니다.
</Callout>

### 2. 환경 변수 설정

App의 공개 주소에서 slug를 확인합니다. 예를 들어 `https://github.com/apps/multica-acme`의 slug는 `multica-acme`입니다.

```dotenv
GITHUB_APP_SLUG=multica-acme
GITHUB_WEBHOOK_SECRET=<App을 만들 때 입력한 webhook secret>
FRONTEND_ORIGIN=https://multica.example.com
```

`GITHUB_APP_SLUG`와 `GITHUB_WEBHOOK_SECRET` 중 하나라도 없으면 연결 버튼이 비활성화되고 webhook endpoint도 이벤트 처리를 거부합니다.

다음 두 변수는 PR 카드에서 CI 상태와 merge 가능 여부를 표시하기 위해 필요합니다. Multica는 이 값으로 App 신원을 인증하고 snapshot을 가져옵니다.

```dotenv
GITHUB_APP_ID=<GitHub App 숫자 ID>
GITHUB_APP_PRIVATE_KEY=<BEGIN/END 줄과 줄바꿈을 유지한 전체 PEM private key>
```

Private key는 GitHub App의 **Private keys → Generate a private key**에서 생성합니다. 설정하지 않으면 연동 기능이 자연스럽게 축소됩니다. PR은 계속 미러링되고 이슈 자동 연결과 merge 시 Done 전환도 정상적으로 작동하지만 PR 카드에 CI 또는 merge 상태가 표시되지 않습니다.

### 3. 데이터베이스 업데이트 및 연결

기존 배포를 업그레이드할 때는 먼저 일반 데이터베이스 migration을 실행합니다.

```bash
make migrate-up
```

API 서비스를 다시 시작한 뒤 **설정 → GitHub**에서 연결을 완료합니다.

## 자주 묻는 문제

- **연결 버튼을 사용할 수 없음**: `GITHUB_APP_SLUG`와 `GITHUB_WEBHOOK_SECRET`이 API 프로세스에 전달되었는지 확인합니다.
- **Webhook이 401을 반환함**: GitHub App과 API가 같은 Webhook secret을 사용하는지 확인하고 GitHub의 **Recent Deliveries**에서 다시 전달합니다.
- **PR이 연결되지 않음**: 저장소가 App 승인 범위에 있는지, 자동 연결이 켜져 있는지, 번호가 현재 워크스페이스에 속하는지 확인합니다.
- **본문에 번호를 썼지만 표시되지 않음**: `Closes MUL-123`을 사용하거나 번호를 브랜치 이름 또는 PR 제목에 넣습니다.
- **CI 상태가 없음**: `GITHUB_APP_ID`와 `GITHUB_APP_PRIVATE_KEY`가 설정되었는지, App에 Checks 및 Commit statuses 읽기 권한이 있고 관련 이벤트를 구독했는지 확인합니다. 설치된 App에 권한을 추가한 뒤에는 각 installation owner가 GitHub에서 승인해야 적용됩니다.
- **PR merge 후 이슈가 완료되지 않음**: PR에 종료 문구가 있는지 확인하고 다른 연결 PR이 Open 또는 Draft 상태로 남아 있는지 확인합니다.

## 다음 단계

- [이슈](/issues) — 상태 전환과 PR merge 시 Done 전환의 관계를 알아봅니다.
- [프로젝트 리소스](/project-resources) — 에이전트 실행에서 사용할 저장소를 정합니다.
- [환경 변수](/environment-variables) — 자체 호스팅 GitHub App의 전체 설정을 확인합니다.