Vista previa de GitLab Pages

Tutoriales
GitLab

Al escribir publicaciones en mi blog relacionadas con Apache APISIX, deseo que mis compañeros las revisen primero. Sin embargo, dado que es mi blog y mezclo publicaciones personales y de negocios, quiero mantenerlas fuera del repositorio. Necesito una vista previa accesible solo para un selecto grupo de personas, algo similar a la vista previa de Vercel. Estoy utilizando GitLab Pages, y no existe tal función incorporada.

I tried two methods: GitHub gists and PDFs. Both have issues.

Los Gists no se muestran tan bien como la página final. Intenté mejorar la situación utilizando DocGist. Es una mejora, aunque no sea la panacea.

Además, los gists no muestran imágenes ya que escribo mis publicaciones en Asciidoc. Debo colocar imágenes en comentarios, lo que interrumpe el flujo. He intentado adjuntar las imágenes al gist, pero no aparecen en el flujo de la publicación en ningún caso. El beneficio sobre los comentarios es que están ordenados; el inconveniente es que necesito cambiar el 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.

Sin embargo, los PDFs tienen problemas propios: una “página” web puede ser potencialmente infinita, mientras que una página de PDF estándar corta la anterior en páginas estándar. Las divisiones pueden ocurrir a través de diagramas. Además, los PDFs dificultan mucho la distribución.

En esta publicación, describiré cómo configuré GitLab Pages para obtener la vista previa que deseo.

Resumen de GitLab Pages

GitLab Pages son similares a GitHub Pages:

Con GitLab Pages, puedes publicar sitios web estáticos directamente desde un repositorio en GitLab.

Para publicar un sitio con Pages, puedes utilizar cualquier generador de sitios estáticos, como Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo o Brunch. También puedes publicar cualquier sitio escrito directamente en HTML plano, CSS y JavaScript.

— GitLab Pages

Así es como ves esta entrada de blog. No encontré una función de vista previa para GitLab Pages. Pedí a expertos sin éxito; GitLab no ofrece vistas previas.

Organización del Trabajo

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.

La idea es crear un artefacto así, accesible bajo una URL, que no pueda predecirse fácilmente. Luego puedo compartir la URL con mis colegas y pedirles su revisión. Para comenzar, podemos copiar la compilación existente en master:

YAML

  

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

En este punto, el sitio está disponible en https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html. Sin embargo, hay muchos problemas que necesitan solución.

Haciéndolo Funcionar

Corrijamos los problemas por orden de importancia.

Solución de Permisos de Acceso

El proyecto es privado; por lo tanto, solo yo puedo acceder al artefacto: esto socava el propósito inicial de ofrecer la vista previa a otros.

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.

Según la documentación, también debes hacer que tu pipeline sea público. Ve a Ajustes > CI/CD > Tuberías generales y marca la casilla de Tuberías públicas.

Solución de Enlaces Relativos

I use Jekyll to build HTML from Asciidoc. To generate links, Jekyll uses two configuration parameters:

  • El dominio, por ejemplo, , se establece con url
  • El camino, por ejemplo, /, establecido con baseurl

Ambos son diferentes en la vista previa. Debes establecer esos parámetros en un archivo de configuración YAML; no hay alternativa de variable de entorno.

Cambiemos la compilación en consecuencia:

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

  1. Establece url utilizando la variable de entorno CI_PROJECT_NAMESPACE. Podría haber utilizado un valor codificado de forma rígida ya que es estático, pero hace que el script sea más reutilizable
  2. Establece baseurl utilizando las variables de entorno CI_PROJECT_NAME y CI_JOB_ID. La última es la parte aleatoria del requisito
  3. Muestra el contenido de la configuración para fines de depuración
  4. Úsalo!

Mejorando la Usabilidad

Es una tarea tediosa intentar distribuir la URL correcta cada vez. Mejor escribirlo en la consola después de compilar:

YAML

  

after_script: echo https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html

Todavía falta un detalle. GitLab Pages ofrece una página de índice. Por ejemplo, si solicitas https://blog.frankel.ch, ellos servirán el archivo raíz index.html. Con artefactos simples, no es así. Dado que solo quiero ofrecer una sola publicación para vista previa, no es un problema, así que no investigué más la configuración.

Uso

En este punto, solo necesito enviar a mi rama preview:

Shell

  

git push --force origin HEAD:preview

La guinda del pastel, no necesitamos tener la rama localmente; simplemente envía a la rama remota.

Conclusión

En esta publicación, mostré cómo previsualizar GitLab Pages y compartir la URL de la vista previa con compañeros de equipo en un par de pasos. La parte más difícil fue darse cuenta de que los artefactos web se renderizan regularmente con el navegador.

Para ir más allá:

Source:
https://dzone.com/articles/gitlab-pages-preview