Historiquement, les CMS ont d’abord utilisé des bases de données (SQL puis noSQL pour certains). Pour les développeurs, c’est très pratique car ces bases sont conçues pour retrouver facilement et efficacement des contenu correspondant à des critères de recherche.

Mais pour les utilisateurs, ça l’est moins car pour accéder au contenu, on doit systématiquement passer par un outil (le CMS ou le client spécifique de la base). Ça ajoute des étapes à la sauvegarde et c’est franchement pénible si on veut modifier un article sans passer par le CMS.

Puis sont arrivé les CMS « à base de fichiers » qui, comme leur nom l’indique, oublient les bases de données et stockent tout dans des fichiers. Pour les développeurs, c’est moins pratique car ils doivent gérer eux-même les recherches (et les indexes éventuels) et ajouter un système de cache pour accélérer la réponse aux requêtes.

Mais pour les utilisateur, c’est bien plus pratique, on peut accéder au contenu avec un simple navigateur de fichier et modifier les article se fait avec n’importe quel éditeur de texte. La sauvegarde ne consiste qu’à copier un répertoire, la restauration, à copier en sens inverse…

Avec un système si facile à copier et dupliquer, on a inévitablement pensé à versionner tous ces fichiers. On aurait pu utiliser CVS et SVN s’ils n’étaient pas devenus obsolètes entre-temps. On aurait aussi pu utiliser mercurial mais la mode a voulu qu’on utilise git (github y étant sans doute pour quelque chose).

Comme tous les CMS à base de fichier qui se respectent, grav a donc un plugin spécifique pour s’occuper du versionnage et de la synchronisation avec vos dépôts préférés.

Installation du plugin

L’installation du plugin est on ne peut plus classique.

En ligne de commande

Même si ce plugin est plus utile lorsque votre cms a une interface graphique d’administration, vous pouvez l’installer en ligne de commande comme les autres.

./bin/gpm install git-sync

Notez que si tous vos fichiers sont la propriété d’un autre utilisateur (i.e. www-data), vous devez passer par sudo pour lancer le gestionnaire avec l’identité de cet utilisateur. La commande est alors légèrement modifiée comme suit :

sudo -u www-data ./bin/gpm install git-sync

Via l’interface d’administration

Si vous préférez l’interface d’administration, vous pouvez passer par le menu « Plugins » à droite, puis le bouton « + Add » en haut, entrer le nom du plugin dans le champ de saisie puis cliquer sur le bouton « + Install ».

L’interface vous demande alors de confirmer, cliquez sur « ✔ Continue ».

Une fois les étapes d’installation réussies, l’interface vous redirige automatiquement vers la page de configuration du plugin et vous lance l’assistant de configuration.

Configuration du plugin

Tant que vous n’avez pas terminé la configuration du plugin, il suffit de visiter sa page de configuration pour que grav vous lance l’assistant automatiquement. Si pour n’importe quelle raison, il ne le fait pas, vous pouvez le relancer via le bouton « Wizard » en bas de la page (dans la section « Actions »).

La configuration du plugin implique, en parallèle, certaines configurations de votre dépôt. On va donc, dans la suite, passer de l’un à l’autre régulièrement.

Connexion au dépôt

Comme le plugin va avoir besoin de s’authentifier au dépôt, vous allez devoir lui fournir un nom d’utilisateur et un mot de passe valide.

Côté gitlab / LDAP

Vous pourriez lui donner vos propre identifiants mais je ne trouve pas ça très sécurisé car en cas de compromission de votre CMS, ce sont vos propres identifiants qui seront accessibles. Je préfère donc créer un utilisateur spécifique.

Et comme notre GitLab est synchronisé avec notre Active Directory, on lui a restreint ses droits.

Côté grav

Une fois que vous avez un compte pour votre dépôt, vous pouvez faire la première étape de la configuration. Nous avons choisi GitLab, entré le nom du compte et son mot de passe pour la connexion et on clique sur « Next ❯ » en bas de page.

Paramètres du dépôt

Sans surprise, pour que le plugin fonctionne, il lui faut aussi un dépôt avec, et c’est important, au moins un commit sur une branche. Comme vous allez configurer le plugin pour suivre une branche, il faut que votre dépôt en ait une avec un commit.

Côté gitlab

Pour ceux qui utilisent GitLab et qui n’ont pas envie de s’embêter, lors de la création du projet, cochez simplement la case prévue pour créer un README.

N’oubliez pas non plus que pour que ça tombe en marche, l’utilisateur du plugin doit pouvoir pousser ses commits sur la branche. Il faut donc lui donner les droits sur le projet (maintainer sur les branches protégées, developper sinon). Sur GitLab, une fois sur la page de votre projet, allez dans le menu « Members » puis complétez le formulaire d’invitation d’un utilisateur et cliquez sur « Invite ».

Côté grav

Le dépôt étant créé et l’utilisateur ayant les bons droits, vous pouvez faire l’étape 2. Ce écran vous demande les paramètres du dépôt : son adresse (en https) et la branche à suivre.

Heureusement, cet écran a un bouton pour vérifier les paramètres. Abusez-en, ça permet de déboguer au fur et à mesure des réglages. Une fois que ça marche, cliquez sur « Next ❯ ».

WebHook

Jusqu’à présent, le plugin est configuré pour pousser les modification faite avec grav vers le dépôt. Si vous souhaitez que des modifications faites ailleurs et poussées également sur le dépôt soient automatiquement reportées vers votre grav, vous devez configurer un webhook.

Vous pouvez voir les webhook comme des adresse que votre dépôt (GitLab et cie.) appellent lorsque certains événements ont lieu pour prévenir les sites de l’événement et leur permettre d’y réagir.

Côté grav

Cette fois, on commence par grav. Pour augmenter la sécurité, je préfère cocher la case « Use Webhook Secret » ce qui déploie un nouveau champ. Ne changez pas les valeurs et garder cet écran ouvert, on va en avoir besoin pour la configuration côté GitLab.

Côté gitlab

Côté GitLab, nous avons plusieurs choses à faire.

Tout d’abord, si vous utilisez vos propres serveurs avec des IP locales, GitLab va d’abord refuser de s’y connecter. C’est une mesure de sécurité, pour éviter qu’un utilisateur externe de votre GitLab puisse s’en servir pour accéder à votre réseau interne.

Pour la désactiver, allez dans la zone d’administration de votre GitLab, puis dans les paramètre, cherchez la section « Outbound requests » et cochez la case « Allow requests to the local network from web hooks and services ».

Désactiver la restriction ne met pas forcément votre réseau en péril mais fait reposer, un peu plus, votre cloisonnement sur vos pare-feu. Si des restrictions s’imposent, c’est alors vers eux que vous devrez vous tourner.

Deuxième réglage pour les connexions TLS. Par sécurité, je suppose que vous avez configuré HTTPS avec un certificat TLS signé par votre racine. Pour que GitLab reconnaisse votre serveur et accepte de lui envoyer ses requêtes à votre serveur, il faut donc qu’il fasse confiance à votre racine.

Pour ça, vous devez déployer votre certificat racine (appelons-le root.arsouyes.org) en le copiant dans le répertoire /etc/gitlab/trusted-certs/.

sudo cp root.arsouyes.org.crt /etc/gitlab/trusted-certs/

On peut maintenant configurer le webhook. Pour ça, via l’interface graphique de GitLab, allez dans le menu « Settings / Webhooks ». Ici, entrez l’URL de grav en lui ajoutant l’adresse du webhook (dans URL) qu’il vous a donné puis le jeton secrêt (dans Secret Token). Laissez coché « Push Event ».

Descendez la page, vérifiez que la vérification SSL est activée et cliquez sur « Add webhook ».

Inutile de lancer un test du webhook maintenant, tant que vous n’avez pas fini la configuration avec l’assistant, grav répondra des erreurs.

Retour à grav

Revenez à grav et cliquez sur « Next ❯ ».

Quoi synchroniser

Dernière étape, choisissez ce que vous voulez synchroniser. Pas de meilleur choix ici, ça dépend de ce que vous voulez faire :

• Pages contient le contenu du site, coché par défaut et je ne vois pas bien pourquoi vous ne le cocheriez pas,
• Thèmes contient le template, css et cie. pour générer les pages, à cocher si vous voulez le versionner ou y travailler à plusieurs,
• Plugins contient le code source des plugins (mais pas leur configuration),
• Config contient la configuration du site et des plugins (donc potentiellement des informations sensibles, on y reviendra),
• Data contient des données sauvegardées par les plugins (i.e. celui des formulaires).

Faites vos choix et cliquez sur « Next ❯ ».

Le plugin va lancer une première synchronisation.

Détails pratiques

À ce stade, votre plugin est fonctionnel mais il y a quelques détails pratiques à connaître avant de vous lancer définitivement.

Merges automatiques

Lorsqu’on travaille avec git, il arrive parfois qu’on déplace un peut brutalement une branche d’un commit à un autre sans ce soucier que le nouveau commit soit bien un descendant de l’ancien (i.e. lors de rebases). Dans ces cas là, on doit forcer le git push pour que le dépôt accepte de déplacer la branche.

C’est globalement considéré comme une mauvaise pratique lorsque la branche est poussée sur un dépôt central car ça impose quelques précautions avec les autres contributeurs. Mais comme pour toutes les mauvaises habitudes, on le fait parfois quand même.

Pour le coup, le plugin git-sync ne va pas du tout vous aider car lorsqu’il recevra la nouvelle version, il va devoir se débrouiller tout seul, et comme il ne sait pas vraiment quoi penser de ce déplacement de branche un peu brutal, il va merger la branche distante et la sienne puis pousser son résultat vers le dépôt central.

Avec de la chance, tout tombe en marche (parce que les deux branches sont identiques ou compatibles) mais je ne garanti par du résultat que vous obtiendrez.

Si vous déplaciez votre branche pour rendre l’arbre des commit joli (c’est souvent pour ça qu’on rebase en fait), git-sync va non seulement annuler tout votre beau travail de nettoyage, mais va l’empirer puisqu’il va quand même garder vos commits et les merger…

Avec ce plugin, évitez-donc les rebases et autres force commit vers le dépôts.

Ignore files

Deuxième chose, si vous avez besoin de versionner la configuration (en général), vous pouvez le faire en renseignant le répertoire config dans la configuration du plugin. Le truc, c’est que vous ne voulez peut-être pas que la configuration de certains plugins particuliers soient versionnées.

En particulier la configuration de git-sync lui-même. D’un côté parce qu’il contient ses identifiants (et même si le mot de passe est protégé, ça n’est pas une super habitude à prendre). De l’autre parce qu’il contient le nom de la branche qu’il suit (et si vous utilisez plusieurs branches, avec plusieurs grav, les fusions seront pénibles puisque le fichier d’une branche pourra être écrasé avec les donnée d’une autre et votre instance changer suivre une autre branche).

Heureusement (#197), les développeurs ont ajouté une option pour dire au plugin d’ignorer certains fichiers et répertoires en particulier. Si vous voulez que le plugin ignore de synchroniser sa propre configuration, il suffit d’ajouter /config/plugins/git-sync.yaml à l’option « Git Ignore ».

Une fois cette option ajoutée, le plugin la synchronise et ignorera ensuite tous les changements sur ce fichier. S’ils sont fait dans grav, ils ne seront pas envoyés au dépôt. S’ils sont fait dans le dépôt, ils seront ignorés par grav. Vous pourrez donc fusionner tranquillement vos branche, la configuration de git-sync ne sera pas impactée.

Et après

Maintenant, le contenu de votre application grav (les pages et si vous l’avez choisi, les thèmes, plugins et configuration) est synchronisé avec votre dépôt GitLab. Que les modifications aient lieux d’un côté ou de l’autre, le plugin gardera tout le monde synchronisé.

Pour aller encore plus loin, vous pouvez connecter toutes ces applications à un annuaire LDAP (GitLab et grav) puis régler le plugin git-sync pour considérer l’utilisateur connecté comme auteur du commit. Dans la configuration du plugin, modifier la configuration de « Commits Author » pour prendre la valeur « Use Grav User Name ».

Avec ce réglage, les modifications apportées par vos utilisateurs sont liées à un seul compte, celui qu’ils ont sur votre annuaire.