자체 호스팅 Git 코드 호스팅

워크스페이스마다 자체 호스팅 Forgejo, Gitea, GitLab 인스턴스를 연결해 브랜치 이름이나 제목에 태스크 번호가 있거나 본문의 종료 키워드 뒤에 태스크 번호가 있는 Pull Request / Merge Request를 해당 태스크에 자동 연결하고, merge되면 워크스페이스가 정한 상태로 옮기며 CI 상태를 표시합니다.

자체 배포한 Multica에서만 사용할 수 있습니다. 이 연동은 Multica를 직접 배포해 운영할 때만 제공되며 Multica Cloud에서는 사용할 수 없습니다. 여기서 "자체 호스팅"은 Multica 자체를 배포하는 것을 뜻합니다. 일반적으로 자체 네트워크의 Git 인스턴스에 접근하기 위해 사용합니다. 서버 운영자가 MULTICA_VCS_INTEGRATION_ENABLED=true로 기능을 켜고 MULTICA_VCS_SECRET_KEY도 설정해야 합니다. 그전에는 설정 → 코드에 이 행이 표시되지 않습니다.

Multica는 워크스페이스별로 자체 호스팅 Git 코드 호스팅인 Forgejo, Gitea, GitLab 중 하나에 연결합니다. 연결하면 브랜치 이름이나 제목에 태스크 번호(예: MUL-123)가 포함되거나 본문의 종료 키워드 뒤에 태스크 번호(Closes MUL-123)가 있는 Pull Request(GitLab에서는 Merge Request)가 해당 태스크에 자동으로 연결되고 태스크 사이드바의 Pull requests에 표시됩니다. 태스크에 연결된 PR이 모두 merge되면 태스크가 워크스페이스가 정한 상태(기본값 완료)로 이동합니다. head commit의 CI는 카드에 check bar로 표시됩니다.

이 코드 호스팅은 GitHub와 동시에 사용할 수 있으며 워크스페이스 하나에서 원하는 대로 조합할 수 있습니다.

GitHub와 달리 이 코드 호스팅에는 "App" 모델이 없습니다. 워크스페이스마다 인스턴스 URL과 액세스 token을 저장하고 저장소 또는 조직에 Webhook을 등록합니다. Token과 Webhook secret은 모두 암호화되어 저장됩니다.

사전 조건(서버)

먼저 이 배포에서 연동을 켭니다. 기본값은 꺼짐이며 활성화하기 전에는 해당 영역이 표시되지 않습니다.

MULTICA_VCS_INTEGRATION_ENABLED=true

공식 자체 호스팅 docker compose 파일(docker-compose.selfhost.yml)에는 이미 설정되어 있습니다.

그런 다음 서버가 저장된 자격 증명을 암호화할 수 있도록 base64로 인코딩한 32바이트 키를 설정합니다. 설정하지 않으면 연결 양식을 사용할 수 없습니다.

openssl rand -base64 32

MULTICA_VCS_SECRET_KEY=<base64 32바이트 키>

두 값이 모두 필요합니다. 스위치는 기능을 제공할지 결정하고 키는 저장된 token과 Webhook secret을 암호화합니다. 연결, Webhook, 교체 모두 두 설정을 함께 요구합니다.

MULTICA_PUBLIC_URL을 서버의 공개 base URL로 설정하면 Multica가 바로 붙여 넣을 수 있는 Webhook URL을 표시합니다. 설정하지 않으면 화면에 Webhook 경로만 표시되므로 origin을 직접 앞에 붙여야 합니다.

워크스페이스 연결

Git 코드 호스팅에서 저장소 읽기 권한이 있는 액세스 token을 만듭니다.
- Forgejo / Gitea: 설정 → 애플리케이션.
- GitLab: read_api 권한이 있는 개인(또는 그룹/프로젝트) 액세스 token.
Multica에서 설정 → 코드를 열고 셀프 호스팅 Git 행에서 연결을 클릭합니다.
제공자를 선택하고 인스턴스 URL(예: https://forgejo.example.com)과 액세스 token을 입력한 뒤 연결을 클릭합니다. Multica는 저장하기 전에 해당 token으로 인스턴스에 접근해 검증합니다.
연결 후 표시되는 Webhook URL과 Webhook secret을 복사합니다.

Webhook secret은 한 번만 표시됩니다. 페이지를 떠나기 전에 복사하세요. 같은 인스턴스에 다시 연결하면 token과 secret이 교체됩니다.

사설 CA를 사용하는 인스턴스

연결 시 제공자 인증서에 대해 "is signed by a certificate authority this server does not trust"라는 메시지가 나오면, 인스턴스의 HTTPS 인증서가 Multica 서버가 신뢰하지 않는 내부 CA로 발급되었거나 자체 서명된 것입니다. 서버 관리자가 해당 CA를 백엔드 신뢰 저장소에 추가해야 합니다. Helm에서는 backend.extraCACerts.configMap을 설정하고, Docker Compose에서는 CA를 마운트한 뒤 SSL_CERT_DIR을 설정합니다. 자세한 절차는 Private CA certificates를 참고하세요.

연결 요청에는 액세스 token이 포함되므로 Multica는 인증서 검증을 건너뛰는 옵션을 제공하지 않습니다. 인증서가 호스트 이름과 일치하지 않거나 검증에 실패했다는(예: 만료) 메시지가 나오면 인증서 자체를 고쳐야 합니다. CA를 신뢰하는 것으로는 해결되지 않습니다.

Webhook 등록

저장소에서 설정합니다. 모든 저장소를 포함하려면 조직 또는 그룹에서 설정할 수도 있습니다.

Forgejo / Gitea — 설정 → Webhook → Webhook 추가 → Forgejo/Gitea:

대상 URL: 이전 단계의 Webhook URL.
HTTP 메서드 POST, 콘텐츠 유형 application/json.
secret: Webhook secret(X-Gitea-Signature HMAC 검증에 사용).
트리거 이벤트: Pull Request를 선택하고 CI를 미러링하려면 Commit Status도 선택합니다.

GitLab — 설정 → Webhooks:

URL: Webhook URL.
Secret token: Webhook secret(X-Gitlab-Token으로 전송되고 문자열 그대로 비교).
트리거: Merge request events를 활성화하고 CI를 미러링하려면 Pipeline events도 활성화합니다.

Multica는 저장된 secret으로 모든 delivery를 검증하므로 일치하는 secret이 없는 Webhook은 거부됩니다.

미러링되는 내용

Pull / Merge Request — open, closed, merged, draft 상태와 작성자, 브랜치, 그리고 코드 호스팅이 제공하는 경우 diff 통계.
태스크 연결 — 제목이나 브랜치의 번호, 그리고 본문에서 종료 키워드 바로 뒤에 쓴 번호가 PR을 태스크에 연결합니다. 본문의 단순 언급은 연결하지 않습니다. 태스크에 연결된 PR(GitHub와 자체 호스팅 모두)이 모두 merge되면 GitHub와 같은 설정과 규칙에 따라 워크스페이스가 정한 상태로 태스크를 옮깁니다. 제공자를 연결하면 이 페이지에도 같은 PR 병합 후 태스크 상태 설정이 표시됩니다.
CI — Forgejo/Gitea commit status와 GitLab pipeline을 head commit의 통과/실패/진행 중 check bar로 집계합니다.

에이전트의 Pull Request 생성

PR을 만드는 데 Multica의 Git 코드 호스팅 설정은 필요하지 않습니다. 에이전트는 런타임에서 저장소를 checkout하고 런타임 host 자체의 Git 자격 증명으로 브랜치를 push하고 PR을 만듭니다. 에이전트가 특정 코드 호스팅에서 작업하게 하려면 SSH deploy key 또는 host의 Git credential helper에 저장된 token 등을 사용해 데몬 host가 해당 서비스에 인증할 수 있게 하고 평소처럼 저장소 URL을 추가하세요. 저장소 checkout은 모든 Git URL을 지원하므로 제공자별 설정이 필요하지 않습니다.