Git 커넥터

개요

Git 커넥터는 Git 리포지토리의 파일을 가져와서 Fess 인덱스에 등록하는 기능을 제공합니다.

이 기능을 사용하려면 fess-ds-git 플러그인이 필요합니다.

지원 리포지토리

  • GitHub(퍼블릭/프라이빗)

  • GitLab(퍼블릭/프라이빗)

  • Bitbucket(퍼블릭/프라이빗)

  • 로컬 Git 리포지토리

  • 기타 Git 호스팅 서비스

전제조건

  1. 플러그인 설치가 필요합니다

  2. 프라이빗 리포지토리의 경우 인증 정보가 필요합니다

  3. 리포지토리에 대한 읽기 액세스 권한이 필요합니다

플러그인 설치

관리 화면의 “시스템” → “플러그인”에서 설치합니다.

또는 자세한 내용은 플러그인 를 참조하세요.

설정 방법

관리 화면에서 “크롤러” → “데이터 스토어” → “새로 만들기”에서 설정합니다.

기본 설정

항목 설정 예
이름 Project Git Repository
핸들러 이름 GitDataStore
활성화 켬

파라미터 설정

퍼블릭 리포지토리 예:

uri=https://github.com/codelibs/fess.git
base_url=https://github.com/codelibs/fess/blob/master/
extractors=text/.*:textExtractor,application/xml:textExtractor,application/javascript:textExtractor,
prev_commit_id=

프라이빗 리포지토리 예(인증 있음):

uri=https://username:personal_access_token@github.com/company/private-repo.git
base_url=https://github.com/company/private-repo/blob/master/
extractors=text/.*:textExtractor,application/xml:textExtractor,
prev_commit_id=

파라미터 목록

파라미터 필수 설명
uri 예 Git 리포지토리의 URI(clone용)
base_url 아니오 파일 표시용 기본 URL. 설정하지 않으면 URL이 비어 있고 삭제된 파일의 자동 삭제도 비활성화됩니다
username 아니오 Git 인증 사용자 이름. URI에 인증 정보를 포함하는 대안으로 password와 함께 사용합니다
password 아니오 Git 인증 비밀번호 또는 토큰. username과 함께 사용합니다
extractors 아니오 MIME 타입별 추출기 설정
default_extractor 아니오 MIME 패턴이 일치하지 않을 때의 폴백 추출기 (기본값: tikaExtractor)
prev_commit_id 아니오 이전 커밋 ID(차등 크롤링용). 크롤링 성공 후 자동으로 업데이트됩니다
commit_id 아니오 대상 커밋 ID (기본값: HEAD). 브랜치 또는 태그 지정 가능
ref_specs 아니오 Git ref 스펙 (기본값: +refs/heads/*:refs/heads/*)
repository_path 아니오 로컬 리포지토리 경로. 설정하지 않으면 임시 디렉토리가 생성되고 크롤링 후 삭제됩니다
include_pattern 아니오 파일 경로 포함 필터 (정규표현식)
exclude_pattern 아니오 파일 경로 제외 필터 (정규표현식)
max_size 아니오 인덱싱할 최대 파일 크기(바이트 단위, 기본값: 10000000)
cache_threshold 아니오 메모리와 디스크 버퍼링 전환 임계값(바이트 단위, 기본값: 1000000)
readInterval 아니오 각 파일 처리 간격(밀리초 단위, 기본값: 0)

스크립트 설정

url=url
host="github.com"
site="github.com/codelibs/fess/" + path
title=name
content=content
cache=""
digest=author.toExternalString()
anchor=
content_length=contentLength
last_modified=timestamp
mimetype=mimetype

사용 가능한 필드

필드 설명
url 파일 URL
path 리포지토리 내 파일 경로
name 파일명
content 파일 텍스트 콘텐츠
contentLength 콘텐츠 길이
timestamp 최종 수정 일시
mimetype 파일 MIME 타입
author 최종 커밋 작성자 정보 (PersonIdent)
committer 커미터 정보 (PersonIdent). author와 다를 수 있습니다
uri Git 리포지토리 URI

Git 리포지토리 인증

GitHub Personal Access Token

1. GitHub에서 Personal Access Token 생성

https://github.com/settings/tokens 에 접속:

  1. “Generate new token” → “Generate new token (classic)” 클릭

  2. 토큰명 입력(예: Fess Crawler)

  3. 범위에서 “repo” 체크

  4. “Generate token” 클릭

  5. 생성된 토큰 복사

2. URI에 인증 정보 포함

uri=https://username:YOUR_GITHUB_TOKEN@github.com/company/repo.git

GitLab Private Token

1. GitLab에서 Access Token 생성

GitLab의 User Settings → Access Tokens:

  1. 토큰명 입력

  2. 범위에서 “read_repository” 체크

  3. “Create personal access token” 클릭

  4. 생성된 토큰 복사

2. URI에 인증 정보 포함

uri=https://username:YOUR_GITLAB_TOKEN@gitlab.com/company/repo.git

사용자 이름 및 비밀번호 인증

URI에 인증 정보를 포함하는 대신, username 및 password 파라미터를 사용하여 인증 정보를 지정할 수도 있습니다:

uri=https://github.com/company/repo.git
username=your_username
password=YOUR_PERSONAL_ACCESS_TOKEN

username과 password 모두 지정된 경우에만 인증 정보가 사용됩니다.

참고

Git 커넥터는 HTTP/HTTPS 인증(사용자 이름 및 비밀번호, 또는 액세스 토큰)만 지원합니다. SSH 키 인증(git@... 형식의 URI)은 지원되지 않습니다. HTTPS 형식의 URI를 사용하세요.

추출기 설정

MIME 타입별 추출기

extractors 파라미터로 파일 타입별 추출기를 지정:

extractors=text/.*:textExtractor,application/xml:textExtractor,application/javascript:textExtractor,application/json:textExtractor,

형식: <MIME 타입 정규표현식>:<추출기명>,

기본 추출기

  • textExtractor - 텍스트 파일용

  • tikaExtractor - 바이너리 파일용(PDF, Word 등)

텍스트 파일만 크롤링

extractors=text/.*:textExtractor,

모든 파일 크롤링

extractors=.*:tikaExtractor,

특정 파일 타입만

# Markdown, YAML, JSON만
extractors=text/markdown:textExtractor,text/yaml:textExtractor,application/json:textExtractor,

차등 크롤링

이전 커밋 이후 변경 사항만 크롤링

초기 크롤링 후 prev_commit_id에 이전 커밋 ID를 설정:

uri=https://github.com/codelibs/fess.git
base_url=https://github.com/codelibs/fess/blob/master/
prev_commit_id=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

참고

prev_commit_id는 크롤링 성공 후 자동으로 최신 커밋 ID로 업데이트됩니다. 초기 크롤링 시 비워두면 모든 파일이 처리되고, 이후 크롤링에서는 변경 사항만 처리됩니다.

삭제된 파일 처리

base_url이 설정된 경우, Git DiffEntry에서 감지된 삭제 파일(ChangeType.DELETE)은 자동으로 인덱스에서 제거됩니다.

파일이 이름 변경된 경우(ChangeType.RENAME), 이전 경로의 문서는 삭제되고 새 경로의 파일이 재인덱싱됩니다.

참고

삭제된 파일의 자동 제거는 base_url이 설정된 경우에만 유효합니다. base_url이 설정되지 않은 경우 문서 URL이 비어 있으므로 삭제가 수행되지 않습니다.

사용 예

GitHub 퍼블릭 리포지토리

파라미터:

uri=https://github.com/codelibs/fess.git
base_url=https://github.com/codelibs/fess/blob/master/
extractors=text/.*:textExtractor,application/xml:textExtractor,

스크립트:

url=url
host="github.com"
site="github.com/codelibs/fess/" + path
title=name
content=content
last_modified=timestamp
mimetype=mimetype

GitHub 프라이빗 리포지토리

파라미터:

uri=https://username:YOUR_GITHUB_TOKEN@github.com/company/repo.git
base_url=https://github.com/company/repo/blob/main/
extractors=text/.*:textExtractor,application/xml:textExtractor,application/javascript:textExtractor,

스크립트:

url=url
title=name
content=content
digest=author.toExternalString()
content_length=contentLength
last_modified=timestamp
mimetype=mimetype

GitLab(셀프 호스팅)

파라미터:

uri=https://username:glpat-abc123@gitlab.company.com/team/project.git
base_url=https://gitlab.company.com/team/project/-/blob/main/
extractors=text/.*:textExtractor,
prev_commit_id=

스크립트:

url=url
host="gitlab.company.com"
site="gitlab.company.com/team/project/" + path
title=name
content=content
last_modified=timestamp

문서만 크롤링(Markdown 파일)

파라미터:

uri=https://github.com/codelibs/fess.git
base_url=https://github.com/codelibs/fess/blob/master/
extractors=text/markdown:textExtractor,text/plain:textExtractor,

스크립트:

if (mimetype.startsWith("text/")) {
    url=url
    title=name
    content=content
    last_modified=timestamp
}

특정 디렉토리만 크롤링

스크립트로 필터링:

if (path.startsWith("docs/") || path.startsWith("README")) {
    url=url
    title=name
    content=content
    last_modified=timestamp
    mimetype=mimetype
}

문제 해결

인증 오류

증상: Authentication failed 또는 Not authorized

확인 사항:

  1. Personal Access Token이 올바른지 확인

  2. 토큰에 적절한 권한이 있는지 확인(repo 범위)

  3. URI 형식이 올바른지 확인:

    # 올바름
uri=https://username:token@github.com/company/repo.git

# 잘못됨
uri=https://github.com/company/repo.git?token=...

  4. 토큰 유효기간 확인

리포지토리를 찾을 수 없음

증상: Repository not found

확인 사항:

  1. 리포지토리 URL이 올바른지 확인

  2. 리포지토리가 존재하고 삭제되지 않았는지 확인

  3. 인증 정보가 올바른지 확인

  4. 리포지토리에 대한 액세스 권한이 있는지 확인

파일을 가져올 수 없음

증상: 크롤링은 성공하지만 파일이 0개

확인 사항:

  1. extractors 설정이 적절한지 확인

  2. 리포지토리에 파일이 존재하는지 확인

  3. 스크립트 설정이 올바른지 확인

  4. 대상 브랜치에 파일이 존재하는지 확인

MIME 타입 오류

증상: 특정 파일이 크롤링되지 않음

해결 방법:

추출기 설정 조정:

# 모든 파일 대상
extractors=.*:tikaExtractor,

# 특정 MIME 타입 추가
extractors=text/.*:textExtractor,application/json:textExtractor,application/xml:textExtractor,

대형 리포지토리

증상: 크롤링에 시간이 오래 걸리거나 메모리 부족

해결 방법:

  1. extractors로 대상 파일 제한

  2. 스크립트로 특정 디렉토리만 필터링

  3. 차등 크롤링 사용(prev_commit_id 설정)

  4. 크롤링 간격 조정

브랜치 지정

기본 브랜치가 아닌 다른 브랜치를 크롤링하려면 commit_id 파라미터로 브랜치 이름이나 태그를 지정합니다:

uri=https://github.com/company/repo.git
base_url=https://github.com/company/repo/blob/develop/
commit_id=develop

URL 생성

base_url 설정 패턴

GitHub:

base_url=https://github.com/user/repo/blob/master/

GitLab:

base_url=https://gitlab.com/user/repo/-/blob/main/

Bitbucket:

base_url=https://bitbucket.org/user/repo/src/master/

URL은 base_url과 파일 경로를 단순 연결하여 생성됩니다(구분자는 삽입되지 않습니다). 따라서 base_url은 반드시 끝에 /를 포함해야 합니다.

스크립트에서 URL 생성

url=url
title=name
content=content

또는 커스텀 URL:

url="https://github.com/mycompany/repo/blob/main/" + path
title=name
content=content

참고 정보