Wanneer ik blogposts schrijf over Apache APISIX, wil ik dat mijn collega’s ze eerst beoordelen. Het is echter mijn blog en aangezien ik persoonlijke en zakelijke posts vermeng, wil ik ze uit de repository houden. Ik heb een preview nodig die alleen toegankelijk is voor een select gezelschap, iets zoals Vercel’s preview. Ik gebruik GitLab Pages en er is geen dergelijk kant-en-klare functie.
I tried two methods: GitHub gists and PDFs. Both have issues.
Gists worden niet zo mooi weergegeven als de uiteindelijke pagina. Ik heb geprobeerd de situatie te verbeteren door DocGist te gebruiken. Het is een verbetering, zelfs als het geen wondermiddel is.
Bovendien worden afbeeldingen niet weergegeven in gists, aangezien ik mijn posts in Asciidoc schrijf. Ik moet afbeeldingen in opmerkingen plaatsen en dat verstoort de stroom. Ik heb geprobeerd om de afbeeldingen aan de gist toe te voegen, maar ze verschijnen in geen geval in de stroom van de post. Het voordeel boven opmerkingen is dat ze geordend zijn; het nadeel is dat ik de Asciidoc moet aanpassen.
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.
PDF’s hebben echter hun eigen problemen: een web “pagina” is potentieel eindeloos, terwijl een normale PDF-pagina deze in standaardpagina’s verdeelt. Splitsingen kunnen plaatsvinden over diagrammen. Bovendien maakt PDF’s de distributie veel moeilijker.
In deze post zal ik beschrijven hoe ik GitLab Pages heb geconfigureerd om de preview te krijgen die ik wil.
Samenvatting van GitLab Pages
GitLab Pages zijn vergelijkbaar met GitHub Pages:
Met GitLab Pages kun je statische websites direct publiceren vanuit een repository in GitLab.
Om een website te publiceren met Pages, kun je elke statische site generator gebruiken, zoals Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo of Brunch. Je kunt ook elke website publiceren die direct is geschreven in platte HTML, CSS en JavaScript.
Dat is hoe je deze blogpost ziet. Ik vond geen voorvertoningsfunctie voor GitLab Pages. Ik heb experts gevraagd, maar helaas; GitLab biedt geen voorvertoningen.
Opdeling van het werk
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.
Het idee is om een dergelijk artefact te creëren, toegankelijk onder een URL, die niet gemakkelijk te voorspellen is. Ik kan de URL dan met mijn collega’s delen en hen om hun beoordeling vragen. Om te beginnen, kunnen we de bestaande build op master kopiëren:
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: productionOp dit moment is de site beschikbaar op https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html. Er moeten echter nog veel problemen worden opgelost.
Het werk laten lukken
Laten we de problemen oplossen in volgorde van belangrijkheid.
Oplossen van toegangsrechten
Het project is privé; daarom kan alleen ik toegang krijgen tot het artefact: dit ondermijnt het oorspronkelijke doel om de voorvertoning aan anderen te bieden.
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.
Volgens de documentatie moet je ook je pipeline publiek maken. Ga naar Instellingen > CI/CD > Algemene pipelines en schakel het selectievakje Publieke pipelines in.
Oplossen van relatieve links
I use Jekyll to build HTML from Asciidoc. To generate links, Jekyll uses two configuration parameters:
- Het domein, bijvoorbeeld, , wordt ingesteld met
url - Het pad, bijv.,
/, wordt ingesteld metbaseurl
Beide verschillen in de voorvertoning. U moet deze parameters instellen in een YAML-configuratiebestand; er is geen omgevingsvariabele alternatief.
Laten we de build dienovereenkomstig aanpassen:
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- Stel
urlin met behulp van deCI_PROJECT_NAMESPACEomgevingsvariabele. Ik had een hard-coded waarde kunnen gebruiken omdat deze statisch is, maar het maakt de script meer herbruikbaar - Stel
baseurlin met behulp van deCI_PROJECT_NAMEenCI_JOB_IDomgevingsvariabelen. De laatste is het willekeurige deel van de vereiste - Toon de inhoud van de configuratie voor debugdoeleinden
- Gebruik het!
Verbetering van gebruiksvriendelijkheid
Het is vervelend om telkens de juiste URL te verdelen. Beter om het in de console na het bouwen op te schrijven:
after_script: echo https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.htmlEr ontbreekt nog één ding. GitLab Pages bieden een indexpagina. Als u bijvoorbeeld https://blog.frankel.ch opvraagt, zullen ze de hoofdmap index.html leveren. Met alleen artefacten is dit niet het geval. Aangezien ik alleen een enkele post voor voorvertoning wil aanbieden, is dit geen probleem, dus heb ik verder geen onderzoek naar de configuratie gedaan.
Gebruik
Op dit punt hoef ik alleen maar naar mijn preview branch te pushen:
git push --force origin HEAD:previewIcing op de cake, we hoeven de branch niet lokaal te hebben; gewoon naar de remote branch pushen.
Conclusie
In deze post heb ik laten zien hoe je GitLab Pages kunt voorvertonen en de URL van de preview kunt delen met teamleden in een paar stappen. Het moeilijkste deel was om te beseffen dat web-artefacten regelmatig worden weergegeven met de browser.
Verder gaan: