Wenn ich Blog-Beiträge über Apache APISIX schreibe, möchte ich, dass meine Kollegen sie zuerst überprüfen. Da es jedoch mein Blog ist und ich persönliche und geschäftliche Beiträge vermische, möchte ich sie aus dem Repository heraushalten. Ich benötige eine Vorschau, die nur für wenige Personen zugänglich ist, ähnlich wie Vercel’s preview. Ich verwende GitLab Pages, und es gibt keine fertige Funktion dafür.
I tried two methods: GitHub gists and PDFs. Both have issues.
Gists werden nicht so ansprechend angezeigt wie die endgültige Seite. Um die Situation zu verbessern, habe ich DocGist ausprobiert. Es ist eine Verbesserung, wenn auch keine Allheilmittel.
Darüber hinaus zeigen Gists keine Bilder, da ich meine Beiträge in Asciidoc schreibe. Ich muss Bilder in Kommentaren setzen, und das unterbricht den Fluss. Ich habe versucht, die Bilder zum Gist hinzuzufügen, aber sie erscheinen in keinem Fall im Fluss des Beitrags. Der Vorteil gegenüber Kommentaren ist, dass sie geordnet sind; der Nachteil ist, dass ich das Asciidoc ändern muss.
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.
PDFs haben jedoch ihre eigenen Probleme: eine Webseite kann potentiell unendlich sein, während eine reguläre PDF-Seite die vorherige in Standardseiten aufteilt. Aufteilungen können mitten in Diagrammen passieren. Darüber hinaus erschwert PDF die Verteilung erheblich.
In diesem Beitrag werde ich beschreiben, wie ich GitLab Pages konfiguriert habe, um die gewünschte Vorschau zu erhalten.
Zusammenfassung von GitLab Pages
GitLab Pages sind vergleichbar mit GitHub Pages:
Mit GitLab Pages können Sie statische Websites direkt aus einem Repository in GitLab veröffentlichen.
Um eine Website mit Pages zu veröffentlichen, können Sie jeden beliebigen statischen Site-Generator verwenden, wie z.B. Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo oder Brunch. Sie können auch jede Website veröffentlichen, die direkt in reinem HTML, CSS und JavaScript geschrieben wurde.
So sieht man diesen Blog-Beitrag. Ich habe keine Vorschaufunktion für GitLab Pages gefunden. Ich habe Experten gefragt, aber vergeblich; GitLab bietet keine Vorschauen.
Arbeitsaufteilung
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.
Das Ziel ist es, ein Artefakt zu erstellen, das unter einer URL zugänglich ist und nicht leicht vorhersehbar ist. Ich kann die URL dann mit meinen Kollegen teilen und sie um eine Überprüfung bitten. Zunächst können wir die bestehende Build-Datei auf master kopieren:
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: productionAb diesem Zeitpunkt ist die Website unter https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html verfügbar. Es müssen jedoch viele Probleme behoben werden.
Funktionieren lassen
Lassen Sie uns die Probleme in der Wichtigkeit ihrer Behebung bereinigen.
Zugriffsrechte beheben
Das Projekt ist privat; daher kann nur ich auf das Artefakt zugreifen: Dies widerspricht dem ursprünglichen Zweck, eine Vorschau für andere anzubieten.
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.
Laut der Dokumentation müssen Sie auch Ihren Pipeline öffentlich machen. Gehen Sie zu Einstellungen > CI/CD > Allgemeine Pipelines und aktivieren Sie das Kontrollkästchen für öffentliche Pipelines.
Relative Links beheben
I use Jekyll to build HTML from Asciidoc. To generate links, Jekyll uses two configuration parameters:
- Die Domain, z.B., ist mit
urlfestgelegt - Der Pfad, z.B.,
/, der mitbaseurl
beide unterscheiden sich im Vorschaufenster. Sie müssen diese Parameter in einer YAML-Konfigurationsdatei festlegen; es gibt keine Umgebungsvariable als Alternative.
Ändern wir den Build entsprechend:
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- Setzen Sie
urlunter Verwendung derCI_PROJECT_NAMESPACEUmgebungsvariable. Ich hätte einen hartcodierten Wert verwenden können, da er statisch ist, aber es macht das Skript wiederverwendbarer - Setzen Sie
baseurlunter Verwendung derCI_PROJECT_NAMEundCI_JOB_IDUmgebungsvariablen. Letzteres ist der zufällige Teil der Anforderung - Zeige den Inhalt der Konfiguration zum Zweck der Fehlersuche
- Benutze es!
Verbesserung der Benutzerfreundlichkeit
Es ist eine Plackerei, die richtige URL jedes Mal zu verteilen. Besser, sie im Konsolenfenster nach dem Bauen aufzuschreiben:
after_script: echo https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.htmlEs fehlt immer noch ein Stück. GitLab Pages bieten eine Indexseite. Zum Beispiel, wenn Sie https://blog.frankel.ch anfordern, werden sie die Stammseite index.html servieren. Bei einfachen Artefakten ist dies nicht der Fall. Da ich nur einen einzigen Beitrag für die Vorschau anbieten möchte, ist dies kein Problem, also habe ich mich nicht weiter mit der Konfiguration beschäftigt.
Verwendung
Ab diesem Punkt muss ich nur noch zu meiner preview Branch pushen:
git push --force origin HEAD:previewPflicht zur Belohnung, wir müssen die Branch nicht einmal lokal haben; pushe einfach auf den Remote-Branch.
Schlussfolgerung
In diesem Beitrag habe ich gezeigt, wie man GitLab Pages vorab anschauen und die URL der Vorschau mit Teamkollegen teilen kann, und das in wenigen Schritten. Der schwierigste Teil war zu erkennen, dass Web-Artefakte regelmäßig im Browser gerendert werden.
Weiter geht’s: