Quando scrivo post relativi ad Apache APISIX, desidero che i miei colleghi li rivedano prima. Tuttavia, poiché il mio blog mescola post personali e aziendali, voglio tenerli fuori dal repository. Ho bisogno di una anteprima accessibile solo a pochi, qualcosa di simile a Anteprima di Vercel. Sto utilizzando GitLab Pages e non esiste una funzione pronta all’uso per questo.
I tried two methods: GitHub gists and PDFs. Both have issues.
I Gists non si presentano bene come la pagina finale. Ho provato a migliorare la situazione utilizzando DocGist. È un miglioramento, anche se non è la panacea.
Inoltre, i gists non visualizzano immagini poiché scrivo i miei post in Asciidoc. Devo inserire immagini nei commenti, e ciò interrompe il flusso. Ho provato a allegare le immagini al gist, ma non compaiono nel flusso del post in ogni caso. Il vantaggio rispetto ai commenti è che sono ordinati; lo svantaggio è che ho bisogno di modificare 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.
Tuttavia, i PDF hanno problemi propri: una “pagina” web è potenzialmente infinita, mentre una pagina PDF regolare taglia la prima in pagine standard. I tagli possono avvenire attraverso diagrammi. Inoltre, i PDF rendono molto più difficile la distribuzione.
In questo post, descriverò come ho configurato GitLab Pages per ottenere l’anteprima che desidero.
Riassunto di GitLab Pages
I GitLab Pages sono simili a GitHub Pages:
Con GitLab Pages, puoi pubblicare siti web statici direttamente da un repository in GitLab.
Per pubblicare un sito con Pages, puoi utilizzare qualsiasi generatore di siti statici, come Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo o Brunch. Puoi anche pubblicare qualsiasi sito scritto direttamente in HTML, CSS e JavaScript di base.
Ecco come vedi questo post sul blog. Non ho trovato una funzione di anteprima per GitLab Pages. Ho chiesto aiuto agli esperti senza successo; GitLab non offre anteprime.
Disegnare il Lavoro
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’idea è creare un tale artefatto, accessibile tramite un URL, che non sia facilmente prevedibile. Posso quindi condividere l’URL con i miei colleghi e chiedere una loro revisione. Per iniziare, possiamo copiare il build esistente su master:
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: productionA questo punto, il sito è disponibile all’indirizzo https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html. Tuttavia, ci sono molti problemi da risolvere.
Rendendolo Funzionare
Corriamo ai problemi in ordine di importanza.
Risoluzione dei Permessi di Accesso
Il progetto è privato; di conseguenza, solo io posso accedere all’artefatto: questo vanifica l’obiettivo iniziale di offrire l’anteprima ad altri.
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.
Secondo la documentazione, devi anche rendere la tua pipeline pubblica. Vai su Impostazioni > CI/CD > Pipeline generali e seleziona la casella di controllo Pipeline pubbliche.
Correzione dei Collegamenti Relativi
I use Jekyll to build HTML from Asciidoc. To generate links, Jekyll uses two configuration parameters:
- Il dominio, ad esempio, è impostato con
url - Il percorso, ad esempio,
/, impostato conbaseurl
Sono diversi nella anteprima. È necessario impostare questi parametri in un file di configurazione YAML; non esiste un’alternativa a variabili di ambiente.
Cambiamo di conseguenza la build:
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- Imposta
urlutilizzando la variabile di ambienteCI_PROJECT_NAMESPACE. Avrei potuto utilizzare un valore hard-coded poiché è statico, ma rende lo script più riusabile - Imposta
baseurlutilizzando le variabili di ambienteCI_PROJECT_NAMEeCI_JOB_ID. Quest’ultima è la parte casuale del requisito - Visualizza il contenuto della configurazione per scopi di debug
- Usalo!
Miglioramento dell’usabilità
È una noia cercare di distribuire l’URL corretto ogni volta. Meglio scriverlo nella console dopo la build:
after_script: echo https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.htmlC’è ancora un pezzo mancante. GitLab Pages offrono una pagina di indice. Ad esempio, se richiedi https://blog.frankel.ch, serviranno il root index.html. Con artefatti puri, non è così. Dato che voglio solo offrire un singolo post per la preview, non è un problema, quindi non ho approfondito ulteriormente la configurazione.
Uso
A questo punto, ho solo bisogno di inserire nella mia branch preview:
git push --force origin HEAD:previewCome ciliegina sulla torta, non abbiamo bisogno di avere la branch locale; basta inserire nella remota.
Conclusione
In questo post, ho mostrato come visualizzare GitLab Pages e condividere l’URL della anteprima con i compagni di squadra in un paio di passaggi. La parte più difficile è stata rendersi conto che gli artefatti web vengono renderizzati regolarmente con il browser.
Per andare oltre: