Créer son catalogue

Un catalogue public se parcourt dans les deux modes. Un catalogue privé demande le mode serveur, qui conserve votre jeton d’accès — voir Modes de déploiement. Installer une entrée demande le mode serveur dans tous les cas.

Cette page s’adresse à la personne qui met en place le catalogue : elle manipule GitLab, ses jetons et sa CI. Pour simplement parcourir un catalogue existant ou y installer une entrée, voir Catalogue communautaire.

Comment fonctionne un catalogue

Un catalogue ne contient pas les entités elles-mêmes, seulement des renvois. Chaque fiche — un petit fichier dans le dossier entries/ — nomme un dépôt git où vit une entité : un projet, un schéma, un alignement de concepts, un pipeline ETL… Linkr télécharge l’index, affiche les fiches, et clone le dépôt d’une entrée quand vous l’installez.

Les fiches arrivent de deux façons, que l’on combine librement :

• Par scan — le fichier sources.json liste des groupes GitLab (ou des comptes GitHub). Une tâche planifiée les parcourt, sous-groupes compris, et crée une fiche pour chaque dépôt qui contient une entité Linkr — reconnaissable au fichier entity.json que Linkr écrit à la racine quand vous poussez une entité. C’est la voie normale : publier une entité dans un groupe surveillé suffit à la faire apparaître.
• À la main — pour un dépôt situé hors des groupes surveillés, on écrit sa fiche soi-même. Un scan ne supprime jamais une fiche, il signale seulement celles qu’aucun groupe ne couvre.

À partir des fiches, la CI génère deux fichiers que Linkr lit : catalog.json, toutes les fiches complètes, et catalog-index.json, une simple empreinte de chacune. Linkr consulte ce dernier pour savoir si quelque chose a changé, et ne retélécharge le catalogue qu’à ce moment-là — d’où le bandeau Mises à jour disponibles.

Public ou privé

Le catalogue lui-même doit être sur une instance GitLab — gitlab.com, framagit.org, ou le GitLab de votre établissement : Linkr le lit par l’API de GitLab. Les dépôts qu’il liste peuvent être sur GitLab ou sur GitHub.

Étape 1 — partir du modèle

Le modèle de catalogue contient tout le nécessaire : les scripts qui scannent et génèrent l’index, le schéma des fiches et la CI. Il ne demande rien à installer.

Créez sur votre GitLab un projet vide (sans README), puis poussez-y le modèle :

git clone https://framagit.org/interhop/linkr/linkr-catalog-template.git mon-catalogue
cd mon-catalogue
git remote set-url origin git@gitlab.com:mon-equipe/mon-catalogue.git
git push -u origin main

Le menu New project → Import project → Repository by URL de GitLab fait la même chose sans ligne de commande. Choisissez à ce moment la visibilité du projet : Public ou Private.

Étape 2 — dire quoi scanner

Le fichier sources.json, à la racine, liste les groupes à surveiller :

{
  "sources": [
    { "url": "https://gitlab.com/mon-equipe/linkr-content", "note": "Nos entités Linkr" }
  ]
}

Chaque groupe est parcouru avec ses sous-groupes. Les dépôts sans entité Linkr — le catalogue lui-même, un site, un dépôt de code — sont ignorés.

Étape 3 — donner un jeton à la CI

La CI du modèle compte trois tâches — des jobs, dans le vocabulaire de GitLab :

build et rescan écrivent dans le dépôt : ils ont besoin d’un jeton, fourni par une variable de CI nommée CATALOG_BOT_TOKEN. rescan s’en sert aussi pour lire les groupes de sources.json, et ne l’envoie qu’à l’instance GitLab qui héberge le catalogue.

Quel jeton

Le jeton fine-grained se crée depuis votre profil : Edit profile → Access → Personal access tokens → Generate token → Fine-grained token. Deux réglages comptent :

• Group and project access — les groupes (ou sous-groupes) à scanner, plus celui qui contient le catalogue, pour qu’il puisse y pousser.
• Add resource permissions, onglet Group and project — trois ressources à cocher dans le panneau de gauche, chacune avec sa permission dans celui de droite :
  • Project → Read — lister les projets d’un groupe ;
  • Repository → Read — lire leur contenu, dont entity.json ;
  • Code → Download et Push — cloner, et pousser l’index sur main.

Laissez les onglets User et Global vides. Si GitLab répond « Add at least one resource with permissions », c’est que ces permissions n’ont pas été cochées : les groupes choisis plus haut ne suffisent pas.

Où le déposer

Dans le projet du catalogue : Settings → CI/CD → Variables → Add variable.

Notez la date d’expiration du jeton — le fichier MAINTAINING.md du modèle a une ligne pour cela. Ce jour-là, build et rescan échouent avec un message d’authentification qui ne parle pas d’expiration.

Et GitHub ?

Le catalogue lui-même reste sur GitLab : Linkr le lit par l’API de GitLab, et la CI du modèle est une CI GitLab. En revanche, sources.json peut lister des comptes ou organisations GitHub — https://github.com/mon-organisation — à côté des groupes GitLab.

• Seuls les dépôts publics d’un compte GitHub sont scannés, même avec un jeton. Un dépôt GitHub privé s’ajoute par une fiche écrite à la main ; pour l’installer, chaque utilisateur aura besoin, dans Linkr, d’un jeton github.com qui y donne accès.
• Aucun jeton n’est requis, mais GitHub limite les appels anonymes à 60 par heure, vite atteints sur une grosse organisation. Ajoutez alors une seconde variable de CI, GITHUB_TOKEN, créée comme la première (masquée, non protégée). Sur GitHub : Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token, avec Repository access sur Public repositories — en lecture seule, il suffit. Ce jeton n’est envoyé qu’à GitHub.

Étape 4 — programmer le rescan

Dans le projet du catalogue : Build → Pipeline schedules → New schedule.

Le bouton ▶ de la ligne lance le rescan tout de suite, sans attendre lundi. Son journal liste chaque fiche ajoutée (A) ou mise à jour (M) ; il les commite lui-même sur main, il n’y a rien à fusionner. Quand tout est déjà à jour, il se termine en vert avec Nothing to do.

Le rescan se lance aussi à la demande, depuis Build → Pipelines → Run pipeline sur main.

Étape 5 — l’ajouter dans Linkr

Sur la page Catalogue, l’icône d’engrenage — Gérer les catalogues — ouvre la fenêtre Catalogues. Ajouter un catalogue demande un Nom, l’URL du dépôt du catalogue et sa Branche ; le catalogue se charge dès qu’il est ajouté. Le détail de cette fenêtre est décrit dans Utiliser un catalogue interne.

Pour un catalogue privé, activez Dépôt privé et collez votre Jeton d’accès. Ce jeton est le vôtre, pas celui de la CI :

• il est enregistré dans votre compte pour cet hôte — gitlab.com, par exemple — et réutilisé pour tous ses dépôts : lire le catalogue, installer ses entrées, synchroniser avec git. Les autres utilisateurs ne le voient jamais ;
• il doit pouvoir lire le catalogue et les dépôts qu’il liste : un jeton classique avec read_repository suffit — ajoutez write_repository si vous poussez aussi depuis Linkr ;
• chaque utilisateur du serveur saisit le sien.

Si votre compte a déjà un jeton pour cet hôte, le champ le signale ; laissez-le vide pour le conserver.

Ajouter une fiche à la main

Pour un dépôt hors des groupes surveillés, créez un fichier dans entries/, nommé comme son identifiant :

{
  "id": "mes-requetes-icu",
  "type": "sql-collection",
  "git": { "url": "https://gitlab.com/equipe/mes-requetes-icu", "branch": "main" },
  "name": { "en": "ICU queries", "fr": "Requêtes de réanimation" },
  "description": { "en": "Reusable ICU queries.", "fr": "Requêtes réutilisables en réanimation." },
  "badges": ["icu", "omop"]
}

Sont obligatoires id — identique au nom du fichier —, type, git, name et description, avec au moins l’anglais (en) dans ces deux derniers. Le type vaut project, mapping-project, sql-collection, etl-pipeline, data-catalog, dq-rule-set, schema-preset, database ou workspace. La référence complète est le fichier schema/entry.schema.json du modèle.

Lancez ensuite node scripts/build.mjs pour régénérer l’index, puis commitez et poussez — ou ouvrez une merge request : le job validate vérifie la fiche et dit précisément ce qui ne va pas.

Quand un job échoue

Le fichier MAINTAINING.md du modèle reprend ce tableau, avec la marche à suivre.

Pour aller plus loin

• Catalogue communautaire — parcourir un catalogue et installer ses entrées.
• Publier du contenu — préparer une entité avant qu’un catalogue la référence.
• Versioning git — pousser une entité vers son dépôt, ce qui crée son entity.json.