Das Material ist nützlich für Anfänger und diejenigen, die CI / CD für Latex mit integrierten GitHub-Tools schnell erstellen möchten.
Einführung
Als ich neulich mit meinem Lebenslauf im Repository stöberte (ich mache es in Latex, zum Glück gibt es viele Vorlagen ), dachte ich, dass es schön wäre, einen einzigen Ort zu organisieren, an dem die aktuelle Version des Dokuments immer liegt.
Die Grundvoraussetzungen waren einfach:
- Mit minimalem Aufwand, um die Site mit Releases zu erhöhen;
- Aktualisierungen von Inhalten auf der Website werden automatisch vorgenommen.
Eine Lösung in Form einer Pipeline wurde in meinem Kopf gezeichnet:
- Push Commit an GitHub;
- Erstellen von .tex-Dateien in CI / CD;
- Senden gesammelter PDFs an GitHub-Releases;
- Aktualisieren von PDF-Dateien auf der Visitenkartenseite.
In diesem Artikel werden wir uns jeden Schritt genauer ansehen. Die Seite wird GitHub Pages sein. Für CI / CD verwenden wir GitHub-Aktionen.
Wir brauchen:
- GitHub-Konto;
- LaTeX-Kompilierungswerkzeuge;
- Beliebiger Texteditor (ich verwende VIM , das für Latex konfiguriert ist );
Gehen!
GitHub-Aktionen verbinden
Hier können alle Aktionen von der Site aus ausgeführt werden, ohne auf die Konsole zurückzugreifen.
Gehen Sie zu "Aktionen" (rot unterstrichen).
und finden Sie dort die Karte "Einfacher Workflow", auf der Sie auf die Schaltfläche "Diesen Workflow einrichten" klicken
Ein Editor mit einer Workflow-Vorlage wird vor uns geöffnet. Es lohnt sich, näher auf diesen Punkt einzugehen.
GitHub-Aktionen funktionieren mit Workflows , die in separaten Dateien beschrieben werden. Jeder Workflow besteht aus:
- Name (Abschnitt
name: …); - Startbedingungen (Abschnitt
on: …); - Liste der auszuführenden Aufgaben (Abschnitt
jobs: …)
Jeder Job besteht auch aus kleineren Teilen, die als Schritt bezeichnet werden . Jeder Schritt ist eine atomare Aktion (auf einmal ausgeführt). In diesem Fall hat step einen eigenen Namen (
name: …) und eine Liste von Befehlen ( run: …) und kann auch eine vorgefertigte Aktion ( uses: …) von Drittentwicklern verwenden. Aktionen von
Drittanbietern sind der mächtigste Teil von GitHub-Aktionen. Sie können viele Dinge tun: das JDK installieren , Python-Tests in tox ausführen und vieles mehr. In diesem Tutorial verwenden wir xu-cheng / latex-action @ v2 , um Latex zu kompilieren (es gab keine Probleme mit Cyrillic) undActions / Upload-Artefakt @ v2 zum Hochladen von Artefakten.
Kehren wir zu unserem Editor zurück. Die vorgeschlagene Vorlage kann korrigiert und in das folgende Formular gebracht werden:
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
Speichern Sie es in einer Datei, wählen Sie einen beliebigen Dateinamen (Sie können latex.yml verwenden). Nachdem Sie die Erstellung der Datei an die Web-Editoren übergeben haben, sollte der erste Build an GitHub Actions gesendet werden, wodurch ein Artefakt angezeigt wird - das kompilierte PDF.
Hurra! Jetzt können Sie mit der Freigabe beginnen.
Automatische Freigaben einrichten
Das Release-System in GitHub hat eine Besonderheit: Ein Release ist immer an ein Commit mit einem Tag gebunden. Daher haben wir zwei Möglichkeiten:
- Fügen Sie Tags manuell zu den Commits hinzu, für die wir PDF-Dateien sammeln und freigeben möchten.
- Kennzeichnen Sie alle Commits automatisch und geben Sie sie frei.
Für mich schien die zweite Option bequemer. Normalerweise verpflichte ich mich und drücke nur dann, wenn die Arbeit abgeschlossen ist (entweder logisch oder für heute). Deshalb werde ich in Zukunft über ihn sprechen.
Um ein Release zu erstellen, verwenden wir die Aktion Actions / Create-Release @ v1 und um eine PDF-Datei in das erstellte Release hochzuladen (ja, es wird separat hochgeladen), verwenden wir Actions / Upload-Release-Asset @ v1 .
Fügen wir einen neuen Job hinzu:
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
Zur Workflow-Datei hinzufügen und die Änderungen festschreiben. Gehen Sie zu Aktionen und sehen Sie, dass ein weiterer Schritt hinzugefügt wurde:
Gleichzeitig erschien das kompilierte PDF auch in Releases.
Sie müssen es nur noch auf die Website hochladen.
GitHub-Seiten aufrufen
GitHub bietet jedem Projekt die Möglichkeit, eine Webseite zu erstellen, und bietet kostenloses Hosting dafür. Aber Sie müssen JS / CSS / HTML nicht kennen, um etwas Wertvolles zu schreiben! Der Service bietet sofort mehrere hübsche Vorlagen, mit denen das Layoutproblem vollständig gelöst werden kann. Sie müssen lediglich das Markdown-Dokument ausfüllen, den Rest erledigt das System.
Wir gehen zum Abschnitt "Einstellungen" des Repositorys und scrollen auf der Registerkarte "Optionen" (standardmäßig zuerst geöffnet) nach unten zu "GitHub-Seiten".
Hier wählen wir den Hauptzweig als Quelle und / docs als Ordner aus (Sie können auch / root verwenden, aber ich bevorzuge es, die Mindestanzahl von Dateien im Projektstamm zu behalten). Klicken Sie auf "Speichern".
Die Schaltfläche "Themenauswahl" öffnet eine Galerie mit Vorlagen, in denen jede durch Klicken auf die grüne Schaltfläche "Thema auswählen" angezeigt, angezeigt und ausgewählt werden kann.
Nach Auswahl eines Themas werden wir in den Web-Editor geworfen, wo vorgeschlagen wird, die Markdown-Datei zu bearbeiten, die dann zur Site wird. Hier können Sie alles beschreiben, was Ihr Herz begehrt: von einer einfachen Präsentation Ihrer selbst bis zu den Zielen des Dokuments und den Merkmalen der Arbeit.
Wenn Sie mit dem Inhalt zufrieden sind, übernehmen Sie Ihre Änderungen.
Wo ist meine Seite?
Der Link zur zusammengestellten Seite wird immer unter Einstellungen -> GitHub-Seiten gespeichert. Es ist besser, es auf der Website des Repositorys zu registrieren (das Zahnrad neben dem Feld "Info" auf der Hauptseite), um es nicht zu verlieren.
Herunterladen der neuesten Version
Es gibt einen kleinen Trick: Auf die neueste Version und alle ihre Dateien kann immer verwiesen werden, indem das Commit-Tag in der URL durch "neueste" ersetzt wird. In unserem Beispiel müssen wir einen Link einfügen , um die Datei my_asset_name.pdf aus der neuesten Version abzurufen
https://github.com/<your_username>/<repo_name>/releases/latest/download/my_asset_name.pdf .
In meinem Fall war es: https://github.com/alekseik1/github_actions_latex_template/releases/latest/download/my_asset_name.pdf .
Nach diesen Schritten verlinken GitHub Pages immer auf die neueste Version.
Ergebnis
Wir haben GitHub-Aktionen eingerichtet, um automatisch eine PDF-Datei zu erstellen, sie freizugeben und eine Site auf GitHub-Seiten mit der neuesten Version aufzurufen. Die endgültige Version des Projekts finden Sie hier .
Vielen Dank für Ihre Aufmerksamkeit!