Si vous hébergez vos projets sur GitHub ou GitLab, vous avez certainement envie d'utiliser l'outil de wiki intégré pour documenter vos projets. Malheureusement, de base il ne prévoit pas d'option pour l'édition communautaire. Voyons comment remédier à cela.

Un dépôt git classique

Saviez-vous que le wiki est en réalité un dépôt git contenant les pages sous forme d'un fichier Markdown ? Grâce à ça nous allons pouvoir utiliser le côté décentralisé de git à notre avantage. L'idée est alors d'avoir un nouveau dépôt git (toujours hébergé sur GitHub ou GitLab) qui sera synchronisé avec le wiki. Il sera ainsi possible de contribuer au wiki via des pull request sur le wiki public.

Tout au long de ce billet, nous verrons comment j'ai mis en place ce procédé pour ACMEd. Il est donc orienté GitHub mais les personnes utilisant GitLab devraient pouvoir l'adapter sans difficultés.

Création d'un jeton d'authentification

La toute première étape a été de me créer un jeton d'authentification GitHub. Pour fonctionner, ce jeton n'a besoin que du droit public_repo car son but sera de permettre l'accès au dépôt du wiki.

Dans ce billet nous utiliserons le jeton fictif suivant : 801f0770d5580fe8fb80871663ce16b8b36794ad.

Création du dépôt wiki public

Je commence par la création d'un dépôt public vide qui accueillera les contributions communautaires sur le wiki : acmed-wiki.

Pour le remplir, je reviens sur le wiki du dépôt principal et le clone :

git clone "https://github.com/breard-r/acmed.wiki.git"

Je vais ensuite supprimer la remote automatiquement créée et, à la place, en ajouter deux nouvelles :

• upstream : le wiki lui-même, authentifié par le jeton d'accès
• contrib : le dépôt public, authentifié par ssh

git remote rm origin
git remote add upstream "https://801f0770d5580fe8fb80871663ce16b8b36794ad@github.com/breard-r/acmed.wiki.git"
git remote add contrib "git@github.com:breard-r/acmed-wiki.git"

Je pousse ensuite dessus le contenu du wiki tout en définissant la remote contrib comme étant celle à utiliser par défaut.

git push -u contrib master

Synchronisation manuelle

À ce stade tout est déjà bon. Tout le monde peut contribuer sur le dépôt public en réalisant une pull request. Pour synchroniser le wiki avec le dépôt local, il suffit de push les commits sur upstream :

git push upstream master

Notez que, si vous réalisez des actions directement depuis l'interface web, vous devrez pull avant de pouvoir push.

git pull upstream master

Synchronisation automatique avec les workflow GitHub

Afin de ne pas avoir à push nous-même sur upstream, il est possible d'utiliser les workflow de GitHub. Commençons par aller dans les paramètres du dépôt de wiki public afin d'y ajouter les deux secrets suivants :

• WIKI_UPSTREAM_URL contenant l'URL du wiki avec jeton d'authentification : https://801f0770d5580fe8fb80871663ce16b8b36794ad@github.com/breard-r/acmed.wiki.git
• WIKI_CONTRIB_URL contenant l'URL du dépôt public : https://github.com/breard-r/acmed-wiki.git

Maintenant que ces secrets sont en place, il est possible de créer un nouveau workflow les utilisant en créant, dans le dépôt local, le fichier .github/workflows/sync.yml :

name: Wiki sync

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  sync:
    name: Sync with the upstream
    runs-on: ubuntu-latest
    steps:
      - name: repo-sync
        uses: wei/git-sync@v2
        with:
            source_repo: ${{ secrets.WIKI_CONTRIB_URL }}
            source_branch: "master"
            destination_repo: ${{ secrets.WIKI_UPSTREAM_URL }}
            destination_branch: "master"

Une fois créé, il ne reste plus qu'à le commit et à push le tout :

git add ".github/workflows/sync.yml"
git commit -m "Add the sync workflow"
git push

Et le tour est joué, ce workflow push automatiquement sur le wiki tout ce qui est push sur la branche master du dépot wiki public.