Когда я пишу блоги, связанные с Apache APISIX, я хочу, чтобы мои коллеги сначала их просмотрели. Однако, поскольку это мой блог, и я смешиваю личные и деловые посты, я хочу их сохранить от репозитория. Мне нужен предварительный просмотр, доступный только для нескольких человек, что-то вроде предварительного просмотра Vercel. Я использую GitLab Pages, и нет такой функции “из коробки”.
I tried two methods: GitHub gists and PDFs. Both have issues.
Gists не отображаются так красиво, как финальная страница. Я попытался улучшить ситуацию, используя DocGist. Это улучшение, хотя и не панацея.
Кроме того, gists не отображают изображения, так как я пишу свои посты в Asciidoc. Я должен размещать изображения в комментариях, и это нарушает поток. Я попытался прикрепить изображения к gist, но они не появляются в потоке поста в любом случае. Плюс в том, что комментарии упорядочены; минус в том, что мне нужно изменить 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.
Однако у PDF есть свои проблемы: веб-страница потенциально бесконечна, в то время как обычная страница PDF разделяет её на стандартные страницы. Разбиения могут происходить через диаграммы. Кроме того, PDF значительно усложняют распространение.
В этом посте я опишу, как я настроил GitLab Pages, чтобы получить нужный мне предварительный просмотр.
Краткое описание GitLab Pages
GitLab Pages похожи на GitHub Pages:
С помощью GitLab Pages вы можете публиковать статические сайты непосредственно из репозитория в GitLab.
Для публикации сайта с помощью Pages вы можете использовать любой генератор статических сайтов, такой как Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo или Brunch. Вы также можете опубликовать любой сайт, написанный непосредственно на обычном HTML, CSS и JavaScript.
Вот так вы видите эту статью блога. Я не нашёл функцию предварительного просмотра для GitLab Pages. Я обратился к экспертам, но безуспешно; GitLab не предлагает предварительных просмотров.
Разбивка работы
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.
Идея заключается в создании такого артефакта, доступного по URL, который нельзя легко предсказать. Затем я могу поделиться URL с коллегами и попросить их провести рецензирование. Для начала мы можем скопировать существующий билд на 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: productionНа данный момент сайт доступен по адресу https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html. Однако нужно исправить множество проблем.
Сделать это рабочим
Давайте исправим проблемы в порядке важности.
Исправление прав доступа
Проект приватный; следовательно, только я могу получить доступ к артефакту: это противоречит изначальной цели предложить превью другим.
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.
Согласно документации, вам также необходимо сделать вашу конвейерную систему публичной. Перейдите в Настройки > CI/CD > Общие конвейеры и установите флажок Public pipelines.
Исправление относительных ссылок
I use Jekyll to build HTML from Asciidoc. To generate links, Jekyll uses two configuration parameters:
- Домен, например, устанавливается с помощью
url - Путь, например,
/, установленный сbaseurl
Оба различаются на превью. Вы должны установить эти параметры в файл конфигурации 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- Установить
urlс использованием переменной окруженияCI_PROJECT_NAMESPACE. Я мог бы использовать жестко закодированное значение, так как оно статично, но это делает скрипт более переносимым - Установить
baseurlс использованием переменных окруженияCI_PROJECT_NAMEиCI_JOB_ID. Последняя является случайной частью требования - Отобразить содержимое конфигурации для отладки
- Используйте это!
Улучшение удобства использования
Это утомительно, пытаться каждый раз распространять правильный URL. Лучше записать его в консоль после сборки:
after_script: echo https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.htmlЕсть еще одна пропущенная часть. GitLab Pages предлагают стартовую страницу. Например, если вы запрашиваете https://blog.frankel.ch, они будут предоставлять корневой index.html. С обычными артефактами это не так. Учитывая, что я хочу предложить только одну запись для предварительного просмотра, это не проблема, поэтому я не исследовал конфигурацию дальше.
Использование
На данный момент мне нужно только отправить на мою ветку preview:
git push --force origin HEAD:previewГлавное, что нам не нужно иметь ветку локально; просто отправьте на удаленный.
Заключение
В этом посте я показал, как предварительно просмотреть GitLab Pages и поделиться URL-адресом предварительного просмотра с коллегами всего за несколько шагов. Самым сложным было осознать, что веб-артефакты рендерятся регулярно с помощью браузера.
Дальнейшие действия: