Ferronier-gitlab

Une extension pour Ferronier pour construire automatiquement une page d’utilisateur·ice ou de groupe, vitrine de ses projets, dans laquelle la moindre des données est obtenue par l’API de GitLab, ce qui signifie que la construction d’une telle vitrine se fait simplement en clonant un dépôt existant. Des exemples sont disponibles pour un utilisateur ou un groupe.

Guide pas à pas

1. Clonez un dépôt existant

  1. Clonez l’un des dépôts d’exemple.

    Cette extension fonctionne de la même manière pour les groupes et les utilisateur·ice·s, donc vous pouvez cloner indifféremment un dépôt prévu pour l’un ou pour l’autre. Voici quelques exemples, sur différentes instances de GitLab :

    Ces dépôts sont proposés comme exemples pratiques grâce auxquels vous pouvez les cloner en un clic, mais vous pouvez aussi copier leur contenu sur n’importe quelle instance GitLab.

  2. Prenez garde à choisir le bon nom de projet.

    Par exemple, si vous souhaitez construire cette vitrine comme la page principale du groupe toto sur https://forge.apps.education.fr, le nom de votre projet doit être toto.forge.apps.education.fr (forge.apps.education.fr étant le nom de domaine associé aux pages GitLab sur cette instance).

    Référez-vous à la documentation officielle pour plus d’informations.

2. Créez un jeton GitLab, et ajoutez-le comme variable de pipeline

La moindre information affichée par cette extension est publique, et récupérée en utilisant l’API de GitLab, mais cette API requiert parfois un jeton pour pouvoir être utilisée.

  1. Créez un jeton d’accès :

    • Pour un groupe [2] :

      1. Allez sur la page de profil de votre groupe.

      2. Choisissez Paramètres > Jetons d'accès.

      3. Choisissez Ajouter un nouveau jeton.

      4. Choisissez un Nom du jeton et, éventuellement, une Description du jeton.

      5. Choisissez une date d’expiration (aussi tard que possible, si vous ne voulez pas répéter cette étape souvent).

      6. Choissez Maintainer comme rôle, et cochez read_api.

      7. Choisissez Créer un jeton d'accès de groupe, et copiez le jeton produit pour l’étape suivante.

    • Pour un·e utilisateur·ice [1] :

      1. Allez sur votre page de profil (dans le coin supérieur droit, cliquez sur votre avatar).

      2. Choisissez Modifier le profil.

      3. Choisissez Access > Jetons d'accès personnel.

      4. Clickez sur Ajouter un jeton.

      5. Choisissez un Nom du jeton et, éventuellement, une Description du jeton.

      6. Choisissez une date d’expiration (aussi tard que possible, si vous ne voulez pas répéter cette étape souvent).

      7. Cochez read_api comme la seule portée.

      8. Cliquez sur Générer un jeton, et copiez le jeton produit pour l’étape suivante.

  2. Ajoutez ce jeton comme variable de pipelines [3] :

    1. Allez sur la page du projet que vous avez créé à l’étape précédente.

    2. Choisissez Paramètres > CI/CD.

    3. Développez la section Variables.

    4. Cliquez sur Ajouter une variable, et complétez les champs :

      • Clé : GITLAB_API_KEY

      • Valeur : le jeton copié dans l’étape précédente.

      • Type : laissez Variable, comme proposé par défaut.

      • autres valeurs : comme vous le souhaitez.

    5. Validez ce formulaire, et allez à l’étape suivante.

3. Lancez votre premier pipeline

Pour produire votre vitrine pour la première fois, vous devez exécuter un pipeline.

  1. Allez sur le dépôt de votre projet.

  2. Choisissez (dans la colonne de gauche) Compilations > Pipelines.

  3. Cliquez sur Nouveau pipeline.

  4. Ne touchez à rien, et validez avec Nouveau pipeline (encore).

Attendez que le pipeline se termine, et vous pouvez aller sur votre site web avec le bouton Gitlab Pages sur la page de votre projet. La page est peut-être plus vide que vous ne le souhaitiez. Si c’est le cas, définir des métadonnées pour vos projets et votre groupe ou profil devrait corriger cela. Ce sera expliqué plus tard.

4. Configurez votre pipeline pour qu’il s’exécute toutes les semaines ou tous les mois

Le site web généré est statique : il montre une capture de vos projets au moment de sa compilation, mais n’est pas mis à jour automatiquement. Pour ce faire, vous pouvez configurer votre dépôt pour qu’il relance le projet toutes les semaines ou tous les mois.

  1. Allez sur le dépôt de votre projet.

  2. Dans le menu de gauche, choisissez Compilation > Planifications de pipeline.

  3. Cliquez sur Nouveau programme (en haut à droite).

  4. Choisissez une description pertinente, votre fuseau horaire, et choisissez le schéma de l’intervalle (chaque mois (voire toutes les semaines) semble correct : avez vraiment besoin d’un intervalle plus court ?). Ne touchez pas au reste, et validez avec le bouton Créer une planification du pipeline.

5. (Optionnel) Lisez et changez certaines options

Le fichier ferronier.toml à la racine de votre dépôt (exemple) contient des options que vous pouvez utiliser pour affiner le résultat de votre site web (par exemple, vous pouvez changer la langue (si des traductions manquent, voyez plus loin), exclure des projets, cachez les sujets…).

6. Définissez les métadonnées de votre profil, groupe et projets, pour qu’elles apparaissent dans votre vitrine

Comme déjà dit (plusieurs fois !), la moindre information affichée sur votre vitrine est obtenue grâce à l’API GitLab, depuis les métadonnées de votre profil, groupe ou projets. Décrivons-les.

Profil utilisateur·ice

_images/user.png

  1. Nom d’utilisateur·ice : Modifier le profil > Paramètres principaux > Nom complet

  2. Avatar : Modifier le profil > Avatar public. S’il n’est pas configuré, la première lettre du nom sera utilisée à la place.

  3. À propos : Modifier le profil > Paramètres principaux > Pronoms, Prononciation, Emplacement, etc. Si certaines informations sont manquantes (n’apparaissent pas dans le site web produit), merci de créer un ticket.

  4. Bio (description courte) : Modifier le profil > Paramètres principaux > Bio.

  5. Liens : Modifier le profil > Paramètres principaux > Comptes sociaux (remarque : certains comptes seront ignorés parce qu’ils n’apparaissent pas dans l’API de Gitlab).

  6. Description longue : Contenu du fichier README d’un projet nommé d’après votre nom d’utilisateur·ice (important !) (documentation officielle).

Groupe

_images/group.png

  1. Nom du groupe : Paramètres > Général > Nom du groupe.

  2. Avatar : Paramètres > Général > Avatar du groupe.

  3. Nombre de projets et sous-groupes : automatique.

  4. Description courte : Paramètres > Général > Description du groupe.

  5. Badges : Paramètres > Badges.

  6. Description longue : Contenu du fichier README d’un projet appelé gitlab-profile (important !) (documentation officielle).

Projet

_images/project.png

  1. Avatar : Paramètres > Général > Avatar du projet. Si non défini, la première lettre du nom du projet sera utilisée à la place.

  2. Nom du projet : Paramètres > Général > Nom du projet.

  3. Chemin : automatique, ne peut pas être modifié.

  4. Description : Paramètres > Général > Description du projet.

  5. Sujets : Paramètres > Général > Sujets du projet.

  6. Badges : Paramètres > Général > Badges.

  7. Page publique : L’URL de la GitLab page (si elle existe).

  8. Liens : automatique.

Remarquez que bien que le README du projet n’apparaisse pas dans la page produite, son contenu est utilisé lors d’une recherche.

Sous-groupe

_images/subgroup.png

  1. Avatar : Paramètres > Général > Avatar du groupe.

  2. Nom du groupe : Paramètres > Général > Nom du groupe.

  3. Chemin : automatique, ne peut pas être modifié.

  4. Description courte : Paramètres > Général > Description du groupe.

  5. Badges : Paramètres > Badges.

  6. Liens : automatique.

Remarquez que bien que le README du groupe (le fichier README d’un projet appelé gitlab-profile (documentation officielle)) n’apparaisse pas sur la page produite, son contenu est utilisé lors des recherches.

Autres forges logicielles ?

Je n’utilise (quasiment ?) pas d’autres forges. Néanmoins, si vous écrivez une extension similaire pour Forgejo, Github, ou n’importe quelle autre forge, je serais ravi de la référencer ici.

Traducations

Le modèle produisant la vitrine, ainsi que cette documentation, sont traduits (en Français seulement, au moment où j’écris cette documentation).

Choisir une langue

Modifiez la ligne locale = "en_US" dans le fichier ferrionier.toml pour utiliser une autre langue.

Ajouter une nouvelle traduction

Les requêtes de fusion pour traduire ferronier-gitlab, ou sa documentation, dans une nouvelle langue, sont les bienvenues ! Suivez cette documentation démarrer.

À propos

Notes