Publié le 25/10/2020.
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.
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.
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
.
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èscontrib
: le dépôt public, authentifié par sshgit 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
À 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
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.