본문으로 건너뛰기

GitLab 통합

자동 분석을 위해 GitLab 저장소를 ArchiCore에 연결합니다.

기능​

  • 셀프 호스팅 지원 — gitlab.com 또는 자체 GitLab 인스턴스 연결
  • 다중 인스턴스 — 여러 GitLab 서버를 동시에 연결
  • 비공개 저장소 — 비공개 프로젝트에 대한 전체 액세스
  • 브랜치 선택 — 분석할 브랜치 선택
  • 자동 분석 — 푸시 이벤트 시 자동 분석
  • 머지 리퀘스트 리뷰 — MR에서 AI 기반 코드 리뷰

설정​

1단계: 개인 액세스 토큰 생성​

  1. GitLab → 설정 → 액세스 토큰으로 이동
  2. 다음 필수 범위로 새 토큰 생성:
    • api — 필수, 전체 API 액세스용 (비공개 저장소, 웹훅, MR 댓글)
    • read_repository — 필수, 저장소 콘텐츠 읽기용
필수 범위

비공개 저장소의 경우 api 범위가 필수입니다. 이 범위가 없으면 저장소 소유자나 관리자라도 ArchiCore가 비공개 프로젝트에 액세스할 수 없습니다.

  1. 토큰 복사 (다시 볼 수 없습니다!)

2단계: GitLab 인스턴스 연결​

웹 인터페이스를 통해:

  1. ArchiCore → 설정 → 통합으로 이동
  2. GitLab 추가 클릭
  3. GitLab URL 입력 (예: https://gitlab.com 또는 https://gitlab.company.com)
  4. 개인 액세스 토큰 붙여넣기
  5. 연결 클릭

API를 통해:

curl -X POST https://api.archicore.io/api/gitlab/instances \
  -H "Authorization: Bearer 귀하의_ARCHICORE_토큰" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceUrl": "https://gitlab.company.com",
    "accessToken": "귀하의_GITLAB_PAT",
    "name": "회사 GitLab"
  }'

3단계: 저장소 연결​

  1. GitLab 인스턴스 연결 후 프로젝트 추가 클릭
  2. GitLab 인스턴스 선택
  3. 저장소 검색
  4. 브랜치 선택
  5. 연결 클릭

셀프 호스팅 GitLab​

ArchiCore는 셀프 호스팅 GitLab 인스턴스를 완전히 지원합니다.

SSL 인증서​

GitLab이 자체 서명 인증서를 사용하는 경우:

  1. 연결 시 "자체 서명 인증서 허용" 활성화
  2. 또는 API 호출에서 rejectUnauthorizedSSL: false 설정

네트워크 액세스​

웹훅이 작동하려면 GitLab 인스턴스가 ArchiCore의 웹훅 엔드포인트에 도달할 수 있어야 합니다:

https://api.archicore.io/api/gitlab/webhook

ArchiCore도 셀프 호스팅인 경우 환경에서 GITLAB_WEBHOOK_URL을 구성하세요.

다중 인스턴스​

여러 GitLab 인스턴스를 연결할 수 있습니다:

  • gitlab.com (공개)
  • gitlab.company.com (기업)
  • gitlab.client.com (클라이언트 프로젝트)

각 인스턴스는 자체 자격 증명으로 별도로 관리됩니다.

Webhooks​

ArchiCore는 다음 용도로 자동으로 웹훅을 생성할 수 있습니다:

  • 푸시 이벤트 — 코드가 푸시될 때 분석 트리거
  • 머지 리퀘스트 이벤트 — MR에 AI 리뷰 코멘트 추가

Webhook 설정​

"자동 분석"이 활성화된 저장소를 연결하면 웹훅이 자동으로 생성됩니다.

수동 웹훅 구성:

  1. GitLab 프로젝트 → 설정 → Webhooks로 이동
  2. URL 추가: https://api.archicore.io/api/gitlab/webhook
  3. 시크릿 토큰: (ArchiCore에서 제공)
  4. 활성화: 푸시 이벤트, 머지 리퀘스트 이벤트

API 참조​

인스턴스 목록​

GET /api/gitlab/instances

인스턴스 추가​

POST /api/gitlab/instances
Content-Type: application/json

{
  "instanceUrl": "https://gitlab.company.com",
  "accessToken": "glpat-xxxxxxxxxxxx",
  "name": "내 GitLab",
  "rejectUnauthorizedSSL": true
}

프로젝트 목록​

GET /api/gitlab/instances/{instanceId}/projects?search=myproject

브랜치 목록​

GET /api/gitlab/instances/{instanceId}/projects/{projectId}/branches

저장소 연결​

POST /api/gitlab/repositories/connect
Content-Type: application/json

{
  "instanceId": "uuid",
  "projectId": 123,
  "autoAnalyze": true,
  "analyzeMRs": true,
  "branch": "main"
}

저장소 연결 해제​

DELETE /api/gitlab/repositories/{repoId}

문제 해결​

"유효하지 않은 토큰"​

  • 만료 확인 — PAT가 만료되지 않았는지 확인
  • 범위 확인 — 토큰에 api 및 read_repository 범위가 있어야 함
  • URL 확인 — 셀프 호스팅 GitLab의 경우 URL이 올바른지 확인 (https:// 포함)
  • 토큰 재생성 — 문제가 지속되면 올바른 범위로 새 토큰 생성

"SSL 인증서 오류"​

  • 연결 시 "자체 서명 인증서 허용" 활성화
  • 또는 CA 인증서를 시스템 신뢰 저장소에 추가

"Webhook이 이벤트를 수신하지 않음"​

  • GitLab이 웹훅 URL에 도달할 수 있는지 확인
  • GitLab → 프로젝트 → 설정 → Webhooks → 최근 전달 확인
  • 웹훅 시크릿이 일치하는지 확인

"저장소를 찾을 수 없음"​

  • 토큰 범위 확인 — 비공개 저장소의 경우 PAT에 api 범위가 있어야 합니다. read_api 범위만으로는 충분하지 않습니다.
  • 토큰 권한 확인 — 저장소 관리자나 소유자라도 범위가 잘못된 토큰으로는 비공개 프로젝트에 액세스할 수 없습니다.
  • 전체 경로 입력 — 연결 시 프로젝트 이름만이 아닌 전체 저장소 경로(예: 그룹/하위그룹/프로젝트이름)를 사용하세요.
  • 아카이브 상태 확인 — 아카이브된 저장소는 검색 결과에 표시되지 않을 수 있습니다.
  • 올바른 인스턴스 확인 — 올바른 GitLab 서버(gitlab.com vs 셀프 호스팅)를 보고 있는지 확인하세요.