Quando escrevo artigos de blog relacionados ao Apache APISIX, quero que meus colegas os revisem primeiro. No entanto, é meu blog e, como misturo postagens pessoais e de negócios, quero mantê-los fora do repositório. Preciso de uma visualização acessível apenas a algumas pessoas, algo como visualização da Vercel. Estou usando o GitLab Pages e não há tal recurso pronto para uso.
I tried two methods: GitHub gists and PDFs. Both have issues.
Os Gists não são exibidos tão bem quanto a página final. Tentei melhorar a situação usando DocGist. É uma melhoria, mesmo não sendo a solução definitiva.
Além disso, os gists não exibem imagens, já que escrevo meus posts em Asciidoc. Tenho que colocar imagens em comentários, o que quebra o fluxo. Tentei anexar as imagens ao gist, mas elas não aparecem no fluxo do post de qualquer maneira. O pro sobre comentários é que eles são ordenados; o contra é que preciso alterar o 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.
No entanto, os PDFs têm seus próprios problemas: uma “página” da web é potencialmente infinita, enquanto uma página de PDF regular corta a primeira em páginas padrão. Os cortes podem ocorrer através de diagramas. Além disso, os PDFs tornam a distribuição muito mais difícil.
Neste post, descreverei como configurei o GitLab Pages para obter a visualização que desejo.
Resumo do GitLab Pages
Os GitLab Pages são semelhantes a GitHub Pages:
Com o GitLab Pages, você pode publicar sites estáticos diretamente de um repositório no GitLab.
Para publicar um site com Pages, você pode usar qualquer gerador de site estático, como Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo ou Brunch. Você também pode publicar qualquer site escrito diretamente em HTML, CSS e JavaScript simples.
É assim que você vê este post de blog. Não encontrei um recurso de visualização para o GitLab Pages. Perguntei a especialistas sem sucesso; o GitLab não oferece visualizações.
Montando o Trabalho
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.
A ideia é criar um artefato assim, acessível sob um URL, que não possa ser facilmente previsto. Posso então compartilhar o URL com meus colegas e pedir a eles para revisarem. Para começar, podemos copiar a construção existente no 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: productionNeste ponto, o site está disponível em https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html. No entanto, muitos problemas precisam ser corrigidos.
Fazendo Funcionar
Vamos corrigir os problemas por ordem de importância.
Corrigindo Permissões de Acesso
O projeto é privado; portanto, só eu posso acessar o artefato: isso contraria o propósito inicial de oferecer a visualização aos outros.
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.
De acordo com a documentação, você também deve tornar seu pipeline público. Vá para Configurações > CI/CD > Pipeline geral e marque a caixa de seleção Pipelines públicas.
Corrigindo Links Relativos
I use Jekyll to build HTML from Asciidoc. To generate links, Jekyll uses two configuration parameters:
- O domínio, por exemplo, , definido com
url - O caminho, por exemplo,
/, definido combaseurl
Ambos são diferentes na visualização. Você deve definir esses parâmetros em um arquivo de configuração YAML; não há alternativa de variável de ambiente.
Vamos alterar a compilação de acordo:
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- Defina
urlusando a variável de ambienteCI_PROJECT_NAMESPACE. Eu poderia ter usado um valor hard-coded já que é estático, mas isso torna o script mais reutilizável - Defina
baseurlusando as variáveis de ambienteCI_PROJECT_NAMEeCI_JOB_ID. O último é a parte aleatória do requisito - Exiba o conteúdo da configuração para fins de depuração
- Use-o!
Melhorando a Usabilidade
É chato tentar distribuir a URL correta a cada momento. Melhor escrevê-la no console após a construção:
after_script: echo https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.htmlAinda falta uma parte. O GitLab Pages oferece uma página inicial. Por exemplo, se você solicitar https://blog.frankel.ch, eles servirão o arquivo raiz index.html. Com artefatos simples, não é o caso. Dado que eu só quero oferecer uma única postagem para visualização, isso não é um problema, então não pesquisei a configuração mais a fundo.
Uso
Neste ponto, só preciso enviar para minha branch preview:
git push --force origin HEAD:previewA cereja no bolo, não precisamos ter a branch localmente; basta enviar para a branch remota.
Conclusão
Neste post, mostrei como visualizar as GitLab Pages e compartilhar o URL da visualização com os colegas em apenas alguns passos. O maior desafio foi perceber que os artefatos da web são renderizados regularmente com o navegador.
Para ir além: