Le matériel sera utile pour les débutants et ceux qui veulent augmenter rapidement CI / CD pour latex avec des outils GitHub intégrés.
introduction
En parcourant le référentiel avec mon CV l'autre jour (je le fais en latex, heureusement, il existe de nombreux modèles ), j'ai pensé qu'il serait bien d'organiser une sorte de lieu unique où se trouve toujours la version actuelle du document.
Les exigences de base étaient simples:
- Avec un minimum d'effort pour augmenter le site avec des versions;
- Rendre automatique les mises à jour du contenu du site.
Une solution sous la forme d'un pipeline a été dessinée dans ma tête:
- Poussez le commit sur GitHub;
- Création de fichiers .tex dans CI / CD;
- Soumettre des fichiers PDF collectés aux versions de GitHub;
- Mise à jour des fichiers pdf sur le site de la carte de visite.
Dans cet article, nous examinerons de plus près chaque étape. Le site sera GitHub Pages. Pour CI / CD, nous utiliserons les actions GitHub.
Nous avons besoin:
- Compte GitHub;
- Outils de compilation LaTeX;
- Tout éditeur de texte (j'utilise VIM configuré pour latex );
Aller!
Connexion des actions GitHub
Ici, toutes les actions peuvent être effectuées à partir du site sans recourir à la console.
Allez dans "Actions" (souligné en rouge).
et trouvez la carte "Flux de travail simple" là-bas, où nous appuyons sur le bouton "Configurer ce flux de travail"
Un éditeur avec un modèle de workflow s'ouvrira devant nous. Il vaut la peine de s'attarder plus en détail sur ce point.
Les actions GitHub fonctionnent avec les workflows , qui sont décrits dans des fichiers séparés. Chaque flux de travail comprend:
- Nom (section
name: …); - Conditions de départ (section
on: …); - Liste des tâches à effectuer (section
jobs: …)
Chaque travail se compose également de petits morceaux appelés step . Chaque étape est une action atomique (réalisée en une seule fois). Dans ce cas, step a son propre nom (
name: …) et une liste de commandes ( run: …), et peut également utiliser une action prête à l'emploi ( uses: …) de développeurs tiers.
Les actions de tiers sont la partie la plus puissante des actions GitHub. Ils peuvent faire beaucoup de choses: installer le JDK , exécuter des tests python dans tox, etc. Dans ce tutoriel, nous utiliserons xu-cheng / latex-action @ v2 pour compiler latex (il n'y a pas eu de problèmes avec le cyrillique) etactions / upload-artifact @ v2 pour télécharger des artefacts.
Revenons à notre éditeur. Le modèle proposé peut être corrigé, l'amenant au formulaire:
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
Enregistrez-le dans un fichier, choisissez n'importe quel nom pour le fichier (vous pouvez utiliser latex.yml). Après avoir validé la création du fichier aux éditeurs Web, la première version doit aller dans GitHub Actions, à la suite de quoi un artefact apparaîtra - le pdf compilé.
Hourra! Vous pouvez maintenant commencer à publier.
Configurer les versions automatiques
Le système de publication sur GitHub a une fonctionnalité: une version est toujours liée à un commit avec une balise. Par conséquent, nous avons deux options:
- Ajoutez manuellement des balises aux commits pour lesquels nous voulons collecter et publier des fichiers pdf;
- Baliser automatiquement tous les commits et les libérer.
Pour moi, la deuxième option me semblait plus pratique. Je m'engage et pousse habituellement juste quand le travail est terminé (soit logiquement soit pour aujourd'hui). Par conséquent, à l'avenir, je parlerai de lui.
Pour créer une version, nous utiliserons l' action actions / create-release @ v1 et pour télécharger un fichier pdf dans la version créée (oui, il est téléchargé séparément), nous utilisons actions / upload-release-asset @ v1 .
Ajoutons un nouveau travail:
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
Ajoutez au fichier de workflow, validez les modifications. Allez dans Actions et voyez qu'une étape supplémentaire a été ajoutée:
Dans le même temps, le pdf compilé est également apparu dans les versions.
La seule chose qui reste est de le télécharger sur le site.
Ouvrir les pages GitHub
GitHub permet à chaque projet de créer une page Web et fournit un hébergement gratuit pour celle-ci. Mais vous n'avez pas besoin de connaître JS / CSS / HTML pour écrire quelque chose de valable! Prêt à l'emploi, le service propose plusieurs jolis modèles qui résolvent complètement le problème de mise en page. Tout ce que vous avez à faire est de remplir le document Markdown, et le système s'occupe du reste.
Nous allons dans la section "Paramètres" du référentiel et dans l'onglet "Options" (ouvert en premier par défaut) descendez jusqu'à "Pages GitHub".
Ici, nous sélectionnons la branche master comme source et / docs comme dossier (vous pouvez également utiliser le / root, mais je préfère garder le nombre minimum de fichiers à la racine du projet). Cliquez sur "Enregistrer".
Le bouton "Sélecteur de thème" ouvre une galerie de modèles, où chacun peut être poussé, visualisé et sélectionné en cliquant sur le bouton vert "Sélectionner un thème".
Après avoir choisi un thème, nous serons jetés dans l'éditeur web, où il est proposé d'éditer le fichier Markdown, qui deviendra alors le site. Ici, vous pouvez décrire tout ce que votre cœur désire: d'une simple présentation de vous-même aux objectifs du document et aux caractéristiques de l'œuvre.
Une fois que vous êtes satisfait du contenu, validez vos modifications.
Où est ma page?
Le lien vers la page assemblée est toujours stocké dans Paramètres -> Pages GitHub. Il est préférable de l'enregistrer sur le site Web du référentiel (l'engrenage à côté du champ «À propos» de la page principale) pour ne pas le perdre.
Téléchargement de la dernière version
Il y a une petite astuce: la dernière version et tous ses fichiers peuvent toujours être référencés en remplaçant la balise de validation dans l'URL par "latest". Dans notre exemple, pour obtenir le fichier my_asset_name.pdf de la dernière version, vous devez insérer un lien
https://github.com/<your_username>/<repo_name>/releases/latest/download/my_asset_name.pdf.
Dans mon cas, c'était: https://github.com/alekseik1/github_actions_latex_template/releases/latest/download/my_asset_name.pdf .
Après ces étapes, les pages GitHub sont toujours liées à la dernière version.
Résultat
Nous avons configuré des actions GitHub pour créer automatiquement un fichier pdf, le mettre en version et ouvrir un site sur les pages GitHub contenant la version la plus récente. La version finale du projet est disponible ici .
Merci de votre attention!