Un relecteur devrait lire le document qu’une pull request modifie, pas un diff d’astérisques. Cette action publie chaque fichier Markdown modifié en page rendue et en commente les liens sur la pull request.
Lire la mise en place dans la documentation
Sans liste de fichiers, l’action demande à git quels fichiers Markdown la pull request a touchés, publie chacun en page en lecture seule et commente un tableau des noms de fichiers, des nombres de mots et des liens. Les fichiers supprimés par la branche sont ignorés, si bien que retirer un document ne fait pas échouer l’exécution.
C’est une action composite, `action.yml` à la racine du dépôt public, et ce qu’elle exécute est le client en ligne de commande du même dépôt : aucun conteneur à télécharger, aucune dépendance à installer, et le même rendu que le site et l’API.
Le commentaire porte le titre Markdown preview. Un relecteur ouvre chaque lien dans un navigateur comme n’importe quelle page, sans application et, pour un lien, sans compte — ce qui permet à quelqu’un qui n’ouvre jamais le diff de relire les textes.
Un diff est la bonne vue pour du code et la mauvaise pour de la prose. Il montre quels mots ont changé et cache si la section se lit encore, si un tableau tombe juste ou si une liste numérotée repart à un en plein milieu. La page rendue y répond d’un coup d’œil, et un relecteur qui n’écrit pas de Markdown peut tout simplement la lire.
Un workflow complet à copier se trouve dans `examples/publish-markdown.yml`. Il s’exécute sur `pull_request` avec un filtre `paths` sur `**.md`, si bien qu’une pull request qui ne touche à aucun Markdown ne lance aucun runner. Le checkout a besoin de `fetch-depth: 0`, car les fichiers modifiés sont calculés par rapport au commit de base de la pull request, et le job a besoin de `pull-requests: write` pour publier le commentaire.
L’étape elle-même tient en `uses: raudarlabs/transformpipe@main` avec une seule entrée, `api-key: ${{ secrets.TP_API_KEY }}`. La clé est une clé API TransformPipe gardée en secret du dépôt, et l’action la transmet au client dans une variable d’environnement plutôt qu’en argument : elle ne fait donc pas partie de la commande écrite dans le journal.
`files` prend des chemins séparés par des espaces à la place de la liste des fichiers modifiés ; c’est ainsi que l’action publie lors d’un push sur une branche plutôt que pour une pull request. `share` vaut `link` par défaut, `people` pour des lecteurs nommés seulement, ou `none` pour garder les documents privés. `merge: true` enchaîne les fichiers en un seul document, nommé par `name`.
`replaces` enregistre un document unique comme nouvelle version d’un document antérieur, `comment: false` supprime le commentaire, et `host` pointe vers un autre déploiement.
Deux sorties reviennent pour les étapes suivantes : `urls`, les liens publiés à raison d’un par ligne, et `documents`, la réponse de l’API pour chaque document, en JSON. Sans rien à publier, l’action le dit, laisse `urls` vide et `documents` en liste vide, et se termine avec succès — une étape ultérieure peut donc se conditionner sur `urls` plutôt qu’échouer.
Chaque exécution publie de nouveaux documents au lieu d’écraser les précédents, si bien que le lien d’un commentaire plus ancien montre toujours ce que disait ce commit. Le prix est un document par fichier et par exécution dans le compte, qui contient 5 000 documents et 250 Mo ; les anciens aperçus se suppriment depuis l’historique.
Publier un lien public demande une adresse e-mail confirmée sur le compte, et tant qu’elle ne l’est pas, l’étape échoue avec cette phrase. Une pull request venant d’un fork s’exécute sans les secrets du dépôt, l’étape n’y a donc pas de clé ; sautez-la avec `if: github.event.pull_request.head.repo.fork == false`.