El material será útil para principiantes y para aquellos que quieran aumentar rápidamente CI / CD para látex con herramientas integradas de GitHub.
Introducción
Mientras navegaba por el repositorio con mi CV el otro día (lo hago en látex, afortunadamente, hay muchas plantillas ), pensé que sería bueno organizar algún tipo de lugar único donde siempre se encuentra la versión actual del documento.
Los requisitos básicos eran simples:
- Con un mínimo esfuerzo para elevar el sitio con lanzamientos;
- Actualice automáticamente el contenido del sitio.
Se dibujó una solución en forma de tubería en mi cabeza:
- Empuje la confirmación en GitHub;
- Construyendo archivos .tex en CI / CD;
- Enviar archivos PDF recopilados a versiones de GitHub;
- Actualización de archivos pdf en el sitio de tarjetas de presentación.
En este artículo, analizaremos más de cerca cada paso. El sitio será Páginas de GitHub. Para CI / CD usaremos Acciones de GitHub.
Nosotros necesitamos:
- Cuenta de GitHub;
- Herramientas de compilación LaTeX;
- Cualquier editor de texto (estoy usando VIM configurado para látex );
¡Vamos!
Conectando acciones de GitHub
Aquí, todas las acciones se pueden realizar desde el sitio sin tener que recurrir a la consola.
Vaya a "Acciones" (subrayado en rojo).
y busque la tarjeta "Flujo de trabajo simple" allí, donde presionamos el botón "Configurar este flujo de trabajo"
Se abrirá un editor con una plantilla de flujo de trabajo frente a nosotros. Vale la pena detenerse en este punto con más detalle.
Las acciones de GitHub funcionan con los flujos de trabajo , que se describen en archivos separados. Cada flujo de trabajo consta de:
- Nombre (sección
name: …); - Condiciones de inicio (sección
on: …); - Lista de tareas a realizar (sección
jobs: …)
Cada trabajo también consta de trozos más pequeños llamados paso . Cada paso es una acción atómica (realizada de una vez). En este caso, el paso tiene su propio nombre (
name: …) y una lista de comandos ( run: …), y también puede usar una acción ( uses: …) preparada por desarrolladores externos.
Las acciones de terceros son la parte más poderosa de las acciones de GitHub. Pueden hacer muchas cosas: instalar el JDK , ejecutar pruebas de Python en tox, y más. En este tutorial, usaremos xu-cheng / latex-action @ v2 para compilar latex (no hubo problemas con Cyrillic) yactions / upload-artifact @ v2 para cargar artefactos.
Volvamos a nuestro editor. La plantilla propuesta se puede corregir llevándola al formulario:
name: Build and deploy latex sources to GitHub Pages
on: push
jobs:
build:
# , . ubuntu
runs-on: ubuntu-latest
steps:
# action,
- uses: actions/checkout@v2
#
- name: Build document
uses: xu-cheng/latex-action@v2
with:
# ,
root_file: main.tex
# .
working_directory: latex_sources/
# , (latexmk)
# -jobname=<name>
args: -jobname=my_doc -pdf -file-line-error -halt-on-error -interaction=nonstopmode
compiler: latexmk
# pdf-
- name: Upload pdf document
uses: actions/upload-artifact@v2
with:
#
name: my_doc
# pdf. «*», «**»
# <working_directory>/<jobname>.pdf
path: latex_sources/my_doc.pdf
Guárdelo en un archivo, elija cualquier nombre de archivo (puede usar latex.yml). Después de enviar la creación del archivo a los editores web, la primera compilación debe ir a Acciones de GitHub, como resultado de lo cual aparecerá un artefacto: el pdf compilado.
¡Hurra! Ahora puedes empezar a lanzar.
Configurar lanzamientos automáticos
El sistema de lanzamiento en GitHub tiene una característica: un lanzamiento siempre está vinculado a una confirmación con una etiqueta. Por tanto, tenemos dos opciones:
- Agregue etiquetas manualmente a las confirmaciones para las que queremos recopilar y publicar archivos pdf;
- Etiquete automáticamente todas las confirmaciones y libérelas.
Para mí, la segunda opción me pareció más conveniente. Por lo general, me comprometo y presiono justo cuando el trabajo está completo (ya sea lógicamente o por hoy). Por eso, en el futuro hablaré de él.
Para crear una versión, usaremos la acción actions / create-release @ v1 y para cargar el archivo pdf en la versión creada (sí, se carga por separado) usaremos actions / upload-release-asset @ v1 .
Agreguemos un nuevo trabajo:
deploy:
runs-on: ubuntu-latest
# master. ,
if: github.ref == 'refs/heads/master'
# job. .
needs: [build]
steps:
# , bash-
- name: Variables
# id : step
id: vars
# echo ${{ steps.<step_id>.outputs.<variable_name> }}
# | — yaml. ,
run: |
echo «::set-output name=date::$(date +'%Y-%m-%d')»
echo «::set-output name=sha8::$(echo ${GITHUB_SHA} | cut -c1-8)»
- name: Download artifacts
uses: actions/download-artifact@v2
with:
# , upload-artifact
name: my_doc
- name: Create Release
uses: actions/create-release@v1
id: create_release
env:
# ., GITHUB_TOKEN
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions
with:
# step id=vars (. ).
# “my_doc-< >-< 8 sha >
tag_name: my_doc-${{ steps.vars.outputs.date }}-${{ steps.vars.outputs.sha8 }}
# ,
release_name: My Actions document (version ${{ steps.vars.outputs.date }})
# , false
draft: false
prerelease: false
# step
- name: Upload pdf asset
uses: actions/upload-release-asset@v1
env:
#
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
# step id=create_release upload_url —
upload_url: ${{ steps.create_release.outputs.upload_url }}
# latex_sources, download-artifacts
asset_path: ./my_doc.pdf
# ,
asset_name: my_asset_name.pdf
asset_content_type: application/pdf
Agregue al archivo de flujo de trabajo, confirme los cambios. Vaya a Acciones y vea que se ha agregado un paso más:
Al mismo tiempo, el pdf compilado también apareció en lanzamientos.
Lo único que queda es subirlo al sitio.
Abrir páginas de GitHub
GitHub ofrece la posibilidad de que cada proyecto cree una página web y proporciona alojamiento gratuito para ella. ¡Pero no tienes que saber JS / CSS / HTML para escribir algo que valga la pena! Fuera de la caja, el servicio ofrece varias plantillas bonitas que resuelven completamente el problema del diseño. Todo lo que necesita hacer es completar el documento de Markdown y el sistema hace el resto.
Vaya a la sección "Configuración" del repositorio y en la pestaña "Opciones" (que se abre primero de forma predeterminada), desplácese hacia abajo hasta "Páginas de GitHub".
Aquí seleccionamos la rama maestra como fuente y / docs como carpeta (también puede usar / root, pero prefiero mantener el número mínimo de archivos en la raíz del proyecto). Clic en Guardar".
El botón "Selector de tema" abre una galería de plantillas, donde cada una se puede tocar, ver y seleccionar haciendo clic en el botón verde "Seleccionar tema".
Después de elegir un tema, seremos lanzados al editor web, donde se propone editar el archivo Markdown, que luego se convertirá en el sitio. Aquí puede describir todo lo que su corazón desea: desde una simple presentación de usted mismo hasta los objetivos del documento y las características del trabajo.
Una vez que esté satisfecho con el contenido, confirme los cambios.
¿Dónde está mi página?
El enlace a la página ensamblada siempre se almacena en Configuración -> Páginas de GitHub. Es mejor registrarlo en el sitio web del repositorio (el engranaje al lado del campo "Acerca de" en la página principal) para no perderlo.
Descargando la última versión
Hay un pequeño truco: siempre se puede hacer referencia a la última versión y todos sus archivos reemplazando la etiqueta de confirmación en la URL con "último". En nuestro ejemplo, para obtener el archivo my_asset_name.pdf de la última versión, necesitamos insertar un enlace
https://github.com/<your_username>/<repo_name>/releases/latest/download/my_asset_name.pdf.
En mi caso fue: https://github.com/alekseik1/github_actions_latex_template/releases/latest/download/my_asset_name.pdf .
Después de estos pasos, las páginas de GitHub siempre se vinculan a la última versión.
Salir
Configuramos Acciones de GitHub para crear automáticamente el archivo pdf, publicarlo y abrir un sitio en las páginas de GitHub que contiene la versión más reciente. La versión final del proyecto se puede encontrar aquí .
¡Gracias por su atención!