Connecteur Git

Apercu

Le connecteur Git fournit la fonctionnalite permettant de recuperer les fichiers d’un depot Git et de les enregistrer dans l’index Fess.

Cette fonctionnalite necessite le plugin fess-ds-git.

Depots pris en charge

  • GitHub (public/prive)

  • GitLab (public/prive)

  • Bitbucket (public/prive)

  • Depot Git local

  • Autres services d’hebergement Git

Prerequis

  1. L’installation du plugin est requise

  2. Pour les depots prives, les informations d’authentification sont necessaires

  3. L’acces en lecture au depot est requis

Installation du plugin

Installez depuis l’interface d’administration via « Systeme » -> « Plugins ».

Ou consultez Présentation pour plus de details.

Configuration

Configurez depuis l’interface d’administration via « Crawler » -> « Data Store » -> « Nouveau ».

Configuration de base

Element Exemple
Nom Project Git Repository
Nom du gestionnaire GitDataStore
Active Oui

Configuration des parametres

Exemple de depot public :

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=

Exemple de depot prive (avec authentification) :

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=

Liste des parametres

Parametre Requis Description
uri Oui URI du depot Git (pour le clone)
base_url Non URL de base pour l’affichage des fichiers. Si non defini, les URLs seront vides et la suppression automatique des fichiers supprimes sera desactivee
username Non Nom d’utilisateur pour l’authentification Git. Utilise avec password comme alternative a l’inclusion des identifiants dans l’URI
password Non Mot de passe ou token pour l’authentification Git. Utilise avec username
extractors Non Configuration des extracteurs par type MIME
default_extractor Non Extracteur de repli quand aucun motif MIME ne correspond (par defaut : tikaExtractor)
prev_commit_id Non ID du commit precedent (pour le crawl differentiel). Mis a jour automatiquement apres un crawl reussi
commit_id Non ID de commit cible (par defaut : HEAD). Une branche ou un tag peut etre specifie
ref_specs Non Git ref specs (par defaut : +refs/heads/*:refs/heads/*)
repository_path Non Chemin du depot local. Si non defini, un repertoire temporaire est cree et supprime apres le crawl
include_pattern Non Filtre d’inclusion des chemins de fichier (regex)
exclude_pattern Non Filtre d’exclusion des chemins de fichier (regex)
max_size Non Taille maximale de fichier a indexer en octets (par defaut : 10000000)
cache_threshold Non Seuil en octets pour le basculement entre la mise en memoire tampon et le disque (par defaut : 1000000)

Configuration du script

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

Champs disponibles

Champ Description
url URL du fichier
path Chemin du fichier dans le depot
name Nom du fichier
content Contenu textuel du fichier
contentLength Longueur du contenu
timestamp Date de derniere modification
mimetype Type MIME du fichier
author Informations sur le dernier auteur du commit (PersonIdent)
committer Informations sur le commiteur (PersonIdent). Peut differer de l’auteur
uri URI du depot Git

Authentification Git

GitHub Personal Access Token

1. Generer un Personal Access Token sur GitHub

Accedez a https://github.com/settings/tokens :

  1. Cliquez sur « Generate new token » -> « Generate new token (classic) »

  2. Entrez un nom de token (ex: Fess Crawler)

  3. Cochez « repo » dans les scopes

  4. Cliquez sur « Generate token »

  5. Copiez le token genere

2. Inclure les informations d’authentification dans l’URI

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

GitLab Private Token

1. Generer un Access Token sur GitLab

Dans GitLab User Settings -> Access Tokens :

  1. Entrez un nom de token

  2. Cochez « read_repository » dans les scopes

  3. Cliquez sur « Create personal access token »

  4. Copiez le token genere

2. Inclure les informations d’authentification dans l’URI

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

Authentification SSH

Pour utiliser une cle SSH :

uri=git@github.com:company/repo.git

Note

Lors de l’utilisation de l’authentification SSH, vous devez configurer la cle SSH de l’utilisateur executant Fess.

Configuration des extracteurs

Extracteurs par type MIME

Specifiez les extracteurs par type de fichier avec le parametre extractors :

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

Format : <regex_type_MIME>:<nom_extracteur>,

Extracteurs par defaut

  • textExtractor - Pour les fichiers texte

  • tikaExtractor - Pour les fichiers binaires (PDF, Word, etc.)

Crawler uniquement les fichiers texte

extractors=text/.*:textExtractor,

Crawler tous les fichiers

extractors=.*:tikaExtractor,

Types de fichiers specifiques uniquement

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

Crawl differentiel

Crawler uniquement les modifications depuis le dernier commit

Apres le premier crawl, definissez l’ID du commit precedent dans prev_commit_id :

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

Note

prev_commit_id est automatiquement mis a jour avec le dernier ID de commit apres un crawl reussi. Laissez-le vide pour le premier crawl afin de traiter tous les fichiers ; les crawls suivants ne traiteront que les modifications.

Traitement des fichiers supprimes

Lorsque base_url est défini, les fichiers détectés comme supprimés via Git DiffEntry (ChangeType.DELETE) sont automatiquement supprimés de l’index.

Exemples d’utilisation

Depot public GitHub

Parametres :

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

Script :

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

Depot prive GitHub

Parametres :

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,

Script :

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

GitLab (auto-heberge)

Parametres :

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=

Script :

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

Crawler uniquement la documentation (fichiers Markdown)

Parametres :

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

Script :

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

Crawler uniquement des repertoires specifiques

Filtrage par script :

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

Depannage

Erreur d’authentification

Symptome : Authentication failed ou Not authorized

Points a verifier :

  1. Verifier si le Personal Access Token est correct

  2. Verifier si le token a les droits appropries (scope repo)

  3. Verifier si le format de l’URI est correct :

    # Correct
uri=https://username:token@github.com/company/repo.git

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

  4. Verifier la date d’expiration du token

Depot introuvable

Symptome : Repository not found

Points a verifier :

  1. Verifier si l’URL du depot est correcte

  2. Verifier si le depot existe et n’a pas ete supprime

  3. Verifier si les informations d’authentification sont correctes

  4. Verifier si vous avez acces au depot

Impossible de recuperer les fichiers

Symptome : Le crawl reussit mais 0 fichiers

Points a verifier :

  1. Verifier si la configuration extractors est appropriee

  2. Verifier si des fichiers existent dans le depot

  3. Verifier si la configuration du script est correcte

  4. Verifier si des fichiers existent dans la branche cible

Erreur de type MIME

Symptome : Certains fichiers ne sont pas crawles

Solution :

Ajuster la configuration des extracteurs :

# Tous les fichiers
extractors=.*:tikaExtractor,

# Ajouter des types MIME specifiques
extractors=text/.*:textExtractor,application/json:textExtractor,application/xml:textExtractor,

Depots volumineux

Symptome : Le crawl prend du temps ou memoire insuffisante

Solution :

  1. Limiter les fichiers cibles avec extractors

  2. Filtrer des repertoires specifiques avec le script

  3. Utiliser le crawl differentiel (parametre prev_commit_id)

  4. Ajuster l’intervalle de crawl

Specification de branche

Pour crawler une branche autre que celle par défaut, spécifiez le nom de la branche ou du tag avec le paramètre commit_id :

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

Generation d’URL

Patterns de configuration 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/

L’URL est generee en concatenant base_url et le chemin du fichier.

Generation d’URL dans le script

url=url
title=name
content=content

Ou URL personnalisee :

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

Informations de reference