Prévisualisation des GitLab Pages

Tutoriels
GitLab

Lorsque j’écris des billets de blog liés à Apache APISIX, je souhaite que mes collègues les relisent en premier. Cependant, c’est mon blog, et puisque je mélange des billets personnels et professionnels, je souhaite les garder hors de la référence. J’ai besoin d’une prévisualisation accessible uniquement à quelques-uns, quelque chose comme la prévisualisation de Vercel. J’utilise GitLab Pages, et il n’y a pas de telle fonctionnalité prête à l’emploi.

I tried two methods: GitHub gists and PDFs. Both have issues.

Les Gists ne s’affichent pas aussi joliment que la page finale. J’ai essayé d’améliorer la situation en utilisant DocGist. C’est une amélioration, même si ce n’est pas la panacée.

De plus, les gists ne montrent pas les images puisque j’écris mes billets en Asciidoc. Je dois placer les images dans des commentaires, et cela brise le rythme. J’ai essayé de joindre les images au gist, mais elles n’apparaissent pas dans le flux du billet de toute façon. Le pro contre les commentaires est qu’ils sont ordonnés; le con est que je dois modifier l’Asciidoc.

I used gists because I’m used to GitHub reviews. But since it’s my blog, I neither need nor want the same kind of reviews as in a regular Merge Request. I need people to point me to when something needs to be clarified or I missed a logical jump, not that I made a typo (I use Grammarly for this). For this reason, a PDF export of a post is enough to review.

Cependant, les PDF ont leurs propres problèmes : une « page » web est potentiellement sans fin, tandis qu’une page PDF standard coupe la première en pages standard. Les divisions peuvent se produire à travers les diagrammes. De plus, les PDF rendent la distribution beaucoup plus difficile.

Dans ce post, je vais décrire comment j’ai configuré GitLab Pages pour obtenir la prévisualisation que je souhaite.

Résumé de GitLab Pages

Les GitLab Pages sont similaires à GitHub Pages :

Avec GitLab Pages, vous pouvez publier des sites web statiques directement à partir d’un dépôt dans GitLab.

Pour publier un site avec Pages, vous pouvez utiliser n’importe quel générateur de site statique, comme Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, ou Brunch. Vous pouvez également publier n’importe quel site écrit directement en HTML, CSS et JavaScript simples.

— GitLab Pages

C’est ainsi que vous voyez ce billet de blog. Je n’ai trouvé aucune fonctionnalité de prévisualisation pour GitLab Pages. J’ai demandé aux experts sans succès; GitLab ne propose pas de prévisualisations.

Organisation du travail

I didn’t believe it initially, but you only need to create a dedicated artifact. Since the artifact consists of web files, the browser will render them.

L’idée est de créer un tel artefact, accessible sous une URL, qui ne peut pas être facilement prédit. Je peux alors partager l’URL avec mes collègues et leur demander de passer en revue. Pour commencer, nous pouvons copier la build existante sur master:

YAML

  

stages:
  - preview

preview:
  stage: preview
  image:
    name: registry.gitlab.com/nfrankel/nfrankel.gitlab.io:latest
  before_script: cd /builds/nfrankel/nfrankel.gitlab.io
  script: bundle exec jekyll b --future -t --config _config.yml -d public
  artifacts:
    paths:
      - public
  only:
    refs:
      - preview
  variables:
    JEKYLL_ENV: production

À ce stade, le site est disponible à l’adresse https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html. Cependant, de nombreux problèmes doivent être résolus.

Rendre Fonctionnel

Corrigeons les problèmes par ordre d’importance.

Correction des Permissions d’Accès

Le projet est privé; par conséquent, seulement moi peux accéder à l’artefact : cela contredit le but initial d’offrir la prévisualisation aux autres.

I want to give my teammates only limited access to my GitLab repository. I gave them Guest access, according to the Principle of least privilege. However, it still didn’t work.

Selon la documentation, vous devez également rendre votre pipeline public. Allez dans Paramètres > CI/CD > Pipelines générales et cochez la case Pipelines publiques.

Correction des Liens Relatifs

I use Jekyll to build HTML from Asciidoc. To generate links, Jekyll uses two configuration parameters:

  • Le domaine, par exemple, , est défini avec url
  • Le chemin, par exemple, /, défini avec baseurl

Sont différents en prévisualisation. Vous devez définir ces paramètres dans un fichier de configuration YAML ; il n’y a pas d’alternative de variable d’environnement.

Changeons donc la construction en conséquence:

YAML

  

preview:
  stage: preview
  image:
    name: registry.gitlab.com/nfrankel/nfrankel.gitlab.io:latest
  before_script:
    - cd /builds/nfrankel/nfrankel.gitlab.io
    - "printf 'url: https://%s.gitlab.io\n' $CI_PROJECT_NAMESPACE >> _config_preview.yml"                        #1
    - "printf 'baseurl: /-/%s/-/jobs/%s/artifacts/public/\n' $CI_PROJECT_NAME $CI_JOB_ID >> _config_preview.yml" #2
    - cat _config_preview.yml                                                                                    #3
  script: bundle exec jekyll b --future -t --config _config.yml,_config_preview.yml -d public                    #4

  1. Définissez url en utilisant la variable d’environnement CI_PROJECT_NAMESPACE. J’aurais pu utiliser une valeur codée en dur puisqu’elle est statique, mais cela rend le script plus réutilisable
  2. Définissez baseurl en utilisant les variables d’environnement CI_PROJECT_NAME et CI_JOB_ID. Cette dernière est la partie aléatoire de la demande
  3. Afficher le contenu de la configuration pour fins de débogage
  4. Utilisez-le!

Amélioration de l’ergonomie

C’est pénible de devoir distribuer chaque fois l’URL correcte. Mieux vaut l’écrire dans la console après la construction:

YAML

  

after_script: echo https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html

Il manque encore un détail. GitLab Pages propose une page d’accueil. Par exemple, si vous demandez https://blog.frankel.ch, ils serviront le fichier racine index.html. Avec des artefacts simples, ce n’est pas le cas. Étant donné que je veux uniquement offrir un seul post pour prévisualisation, ce n’est pas un problème, donc je n’ai pas approfondi la recherche de la configuration.

Utilisation

À ce stade, il ne me reste plus qu’à pousser vers ma branche preview:

Shell

  

git push --force origin HEAD:preview

En prime, nous n’avons pas besoin d’avoir la branche localement ; il suffit de pousser vers la branche distante.

Conclusion

Dans ce post, j’ai montré comment prévisualiser GitLab Pages et partager l’URL de la prévisualisation avec des collègues en quelques étapes. La partie la plus difficile était de réaliser que les artefacts web sont rendus régulièrement avec le navigateur.

Pour aller plus loin:

Source:
https://dzone.com/articles/gitlab-pages-preview