Git-Konnektor

Übersicht

Der Git-Konnektor bietet die Funktionalität, Dateien aus Git-Repositories abzurufen und im Fess-Index zu registrieren.

Für diese Funktion ist das Plugin fess-ds-git erforderlich.

Unterstützte Repositories

  • GitHub (öffentlich/privat)

  • GitLab (öffentlich/privat)

  • Bitbucket (öffentlich/privat)

  • Lokale Git-Repositories

  • Andere Git-Hosting-Dienste

Voraussetzungen

  1. Die Installation des Plugins ist erforderlich

  2. Für private Repositories sind Anmeldedaten erforderlich

  3. Lesezugriff auf das Repository ist erforderlich

Plugin-Installation

Installieren Sie über die Administrationsoberfläche unter „System“ -> „Plugins“.

Oder weitere Details finden Sie unter Plug-ins.

Konfiguration

Konfigurieren Sie über die Administrationsoberfläche unter „Crawler“ -> „Datenspeicher“ -> „Neu erstellen“.

Grundeinstellungen

Einstellung Beispielwert
Name Project Git Repository
Handler-Name GitDataStore
Aktiviert Ein

Parameter-Einstellungen

Beispiel für öffentliches Repository:

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

Beispiel für privates Repository (mit Authentifizierung):

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

Parameterliste

Parameter Erforderlich Beschreibung
uri Ja URI des Git-Repositories (für Clone). Geben Sie in der URI keine Anmeldedaten (Benutzername, Passwort, Token) an, sondern verwenden Sie username und password. uri wird nicht verschlüsselt
base_url Nein Basis-URL für die Dateianzeige. Wenn nicht gesetzt, bleiben URLs leer und die automatische Löschung entfernter Dateien ist deaktiviert
username Nein Git-Authentifizierungsbenutzername. Wird mit password verwendet
password Nein Git-Authentifizierungspasswort oder Token. Wird mit username verwendet. Wird verschlüsselt gespeichert
extractors Nein Extraktoren nach MIME-Typ
default_extractor Nein Fallback-Extraktor, wenn kein MIME-Muster übereinstimmt (Standard: tikaExtractor)
prev_commit_id Nein Vorherige Commit-ID (für differentielles Crawling). Wird nach erfolgreichem Crawling automatisch aktualisiert
commit_id Nein Ziel-Commit-ID (Standard: HEAD). Branch oder Tag kann angegeben werden (für einen Tag siehe auch „Branch angeben“ unten)
ref_specs Nein Git Ref-Specs (Standard: +refs/heads/*:refs/heads/*). Um Tags abzurufen, geben Sie +refs/tags/*:refs/tags/* an (siehe „Branch angeben“ unten)
repository_path Nein Lokaler Repository-Pfad. Wenn nicht gesetzt, wird ein temporäres Verzeichnis erstellt und nach dem Crawling gelöscht
include_pattern Nein Dateipfad-Inklusionsfilter (Regex)
exclude_pattern Nein Dateipfad-Ausschlussfilter (Regex)
max_size Nein Maximale Dateigröße zum Indexieren in Bytes (Standard: 10000000)
cache_threshold Nein Schwellenwert in Bytes für den Wechsel zwischen Speicher- und Festplattenpufferung (Standard: 1000000)
readInterval Nein Verarbeitungsintervall zwischen den einzelnen Dateien (in Millisekunden, Standard: 0)

Skript-Einstellungen

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

Verfügbare Felder

Feld Beschreibung
url URL der Datei
path Dateipfad im Repository
name Dateiname
content Textinhalt der Datei
contentLength Länge des Inhalts
timestamp Datum der letzten Änderung
mimetype MIME-Typ der Datei
author Informationen zum letzten Commit-Autor (PersonIdent)
committer Committer-Informationen (PersonIdent). Kann sich vom Autor unterscheiden
uri Git-Repository-URI

Git-Repository-Authentifizierung

GitHub Personal Access Token

1. Personal Access Token auf GitHub generieren

Besuchen Sie https://github.com/settings/tokens:

  1. Klicken Sie auf „Generate new token“ -> „Generate new token (classic)“

  2. Geben Sie den Token-Namen ein (z.B.: Fess Crawler)

  3. Aktivieren Sie unter Scopes „repo“

  4. Klicken Sie auf „Generate token“

  5. Kopieren Sie das generierte Token

2. Das Token als Passwort angeben

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

GitLab Private Token

1. Access Token auf GitLab generieren

Unter GitLab User Settings -> Access Tokens:

  1. Geben Sie den Token-Namen ein

  2. Aktivieren Sie unter Scopes „read_repository“

  3. Klicken Sie auf „Create personal access token“

  4. Kopieren Sie das generierte Token

2. Das Token als Passwort angeben

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

Authentifizierung mit Benutzername und Passwort

Geben Sie Anmeldedaten über die Parameter username und password an, anstatt sie in uri einzubetten:

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

Anmeldedaten werden nur verwendet, wenn sowohl username als auch password angegeben sind.

Warnung

Geben Sie in uri keine Anmeldedaten an (zum Beispiel https://<token>@github.com/...). uri wird nicht verschlüsselt und in den Datenspeicher-Einstellungen der Administrationsoberfläche sowie in der Admin-API unverändert angezeigt. password wird beim Speichern verschlüsselt. Eine Einstellung mit in der URI eingebetteten Anmeldedaten funktioniert weiterhin, sollte aber auf username und password aufgeteilt werden.

Bemerkung

Der Git-Konnektor unterstützt ausschließlich HTTP/HTTPS-Authentifizierung (Benutzername und Passwort oder ein Zugriffstoken). SSH-Schlüssel-Authentifizierung (URIs im Stil git@...) wird nicht unterstützt. Verwenden Sie eine URI im HTTPS-Format.

Extraktoren konfigurieren

Extraktoren nach MIME-Typ

Mit dem Parameter extractors können Extraktoren nach Dateityp festgelegt werden:

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

Format: <MIME-Typ-Regex>:<Extraktorname>,

Standard-Extraktoren

  • textExtractor - Für Textdateien

  • tikaExtractor - Für Binärdateien (PDF, Word usw.)

Nur Textdateien crawlen

extractors=text/.*:textExtractor,

Alle Dateien crawlen

extractors=.*:tikaExtractor,

Nur bestimmte Dateitypen

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

Differentielles Crawling

Nur Änderungen seit dem letzten Commit crawlen

Nach dem ersten Crawling die prev_commit_id auf die vorherige Commit-ID setzen:

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

Bemerkung

prev_commit_id wird nach einem erfolgreichen Crawling automatisch auf die neueste Commit-ID aktualisiert. Lassen Sie es beim ersten Crawling leer, um alle Dateien zu verarbeiten; nachfolgende Crawlings verarbeiten nur Änderungen.

Verarbeitung gelöschter Dateien

Wenn base_url gesetzt ist, werden über Git DiffEntry (ChangeType.DELETE) erkannte gelöschte Dateien automatisch aus dem Index entfernt.

Wenn eine Datei umbenannt wird (ChangeType.RENAME), wird das Dokument unter dem alten Pfad gelöscht und die Datei unter dem neuen Pfad neu indiziert.

Bemerkung

Die automatische Löschung entfernter Dateien ist nur wirksam, wenn base_url gesetzt ist. Wenn base_url nicht gesetzt ist, ist die Dokument-URL leer, sodass keine Löschung durchgeführt wird.

Anwendungsbeispiele

GitHub öffentliches Repository

Parameter:

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

Skript:

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

GitHub privates Repository

Parameter:

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

Skript:

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

GitLab (selbst gehostet)

Parameter:

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

Skript:

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

Nur Dokumentation crawlen (Markdown-Dateien)

Parameter:

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

Skript:

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

Nur bestimmte Verzeichnisse crawlen

Filterung im Skript:

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

Fehlerbehebung

Authentifizierungsfehler

Symptom: Authentication failed oder Not authorized

Zu überprüfen:

  1. Überprüfen Sie, ob das Personal Access Token korrekt ist

  2. Überprüfen Sie, ob das Token die entsprechenden Berechtigungen hat (repo-Scope)

  3. Überprüfen Sie, ob das URI-Format korrekt ist:

    # Korrekt
uri=https://github.com/company/repo.git
username=your_username
password=YOUR_TOKEN

# Falsch
uri=https://github.com/company/repo.git?token=...

  4. Überprüfen Sie das Ablaufdatum des Tokens

Repository nicht gefunden

Symptom: Repository not found

Zu überprüfen:

  1. Überprüfen Sie, ob die Repository-URL korrekt ist

  2. Überprüfen Sie, ob das Repository existiert und nicht gelöscht wurde

  3. Überprüfen Sie die Anmeldedaten

  4. Überprüfen Sie, ob Sie Zugriff auf das Repository haben

Keine Dateien abrufbar

Symptom: Crawling erfolgreich, aber 0 Dateien

Zu überprüfen:

  1. Überprüfen Sie die extractors-Einstellung

  2. Überprüfen Sie, ob Dateien im Repository existieren

  3. Überprüfen Sie die Skript-Einstellungen

  4. Überprüfen Sie, ob Dateien im Zielbranch existieren

MIME-Typ-Fehler

Symptom: Bestimmte Dateien werden nicht gecrawlt

Lösung:

Passen Sie die Extraktor-Einstellungen an:

# Alle Dateien als Ziel
extractors=.*:tikaExtractor,

# Bestimmte MIME-Typen hinzufügen
extractors=text/.*:textExtractor,application/json:textExtractor,application/xml:textExtractor,

Große Repositories

Symptom: Crawling dauert lange oder Speicherüberlauf

Lösung:

  1. Mit extractors Zieldateien einschränken

  2. Mit Skript nur bestimmte Verzeichnisse filtern

  3. Differentielles Crawling verwenden (prev_commit_id setzen)

  4. Crawl-Intervall anpassen

Branch angeben

Um einen anderen Branch als den Standard zu crawlen, geben Sie den Branch-Namen oder Tag über den commit_id Parameter an:

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

Um einen Tag zu crawlen, muss der Tag abgerufen werden. Wenn die Standard-ref_specs keine Tags abrufen, geben Sie ref_specs=+refs/tags/*:refs/tags/* an (es werden nur Tags abgerufen, keine Branches):

uri=https://github.com/company/repo.git
base_url=https://github.com/company/repo/blob/v1.0/
commit_id=v1.0
ref_specs=+refs/tags/*:refs/tags/*

URL-Generierung

base_url-Muster

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/

Die URL wird durch einfache Verkettung von base_url und dem Dateipfad generiert (ohne eingefügtes Trennzeichen). Daher muss base_url mit einem abschließenden / enden.

URL-Generierung im Skript

url=url
title=name
content=content

Oder benutzerdefinierte URL:

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

Weiterführende Informationen