The material will be useful for beginners and those who want to quickly raise CI / CD for latex with built-in GitHub tools.
Introduction
While browsing the repository with my CV the other day (I am doing it in latex, fortunately, there are many templates ), I thought that it would be nice to organize some kind of single place where the current version of the document always lies.
The basic requirements were simple:
- With minimal effort to raise the site with releases;
- Make content updates on the site automatic.
A solution in the form of a pipeline was drawn in my head:
- Push commit to GitHub;
- Building .tex files in CI / CD;
- Submitting collected pdfs to GitHub releases;
- Updating pdf files on the business card site.
In this article, we'll take a closer look at each step. The site will be GitHub Pages. For CI / CD we will use GitHub Actions.
We need:
- GitHub account;
- LaTeX compilation tools;
- Any text editor (I am using VIM configured for latex );
Go!
Connecting GitHub Actions
Here, all actions can be performed from the site without resorting to the console.
Go to "Actions" (underlined in red).
and find the "Simple workflow" card there, where we press the button "Set up this workflow"
An editor with a workflow template will open in front of us. It is worth dwelling on this point in more detail.
GitHub Actions works with Workflows , which are described in separate files. Each workflow consists of:
- Name (section
name: …); - Start conditions (section
on: …); - List of tasks to be performed (section
jobs: …)
Each job also consists of smaller chunks called step . Each step is an atomic action (done all at once). In this case, step has its own name (
name: …) and a list of commands ( run: …), and can also use a ready-made action ( uses: …) from third-party developers.
Third party actions are the most powerful part of GitHub Actions. They can do many things: install the JDK , run python tests in tox, and more. In this tutorial, we will use xu-cheng / latex-action @ v2 to compile latex (there were no problems with Cyrillic) andactions / upload-artifact @ v2 to upload artifacts.
Let's go back to our editor. The proposed template can be corrected, bringing it to the form:
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
Save it to a file, choose any file name (you can use latex.yml). After committing the creation of the file to the web editors, the first build should go to GitHub Actions, as a result of which the artifact will appear - the compiled pdf.
Hooray! Now you can start releasing.
Setting up automatic releases
The release system in GitHub has one peculiarity: a release is always tied to a commit with a tag. Therefore, we have two options:
- Add tags manually to those commits for which we want to collect and release pdf-files;
- Automatically tag all commits and release them.
For me, the second option seemed more convenient. I usually commit and push exactly when the work is complete (either logically or for today). Therefore, in the future I will talk about him.
To create a release we will use the actions / create-release @ v1 action and to upload a pdf file to the created release (yes, it is uploaded separately) we use actions / upload-release-asset @ v1 .
Let's add a new job:
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
Add to the workflow file, commit the changes. Go to Actions and see that one more step has been added:
At the same time, the compiled pdf also appeared in releases.
The only thing left is to upload it to the site.
Bringing up GitHub Pages
GitHub provides the ability for each project to create a web page and provides free hosting for it. But you don't have to know JS / CSS / HTML to write something worthwhile! Out of the box, the service offers several pretty templates that completely solve the layout issue. All you need to do is fill out the Markdown document, and the system does the rest.
We go to the "Settings" section of the repository and in the "Options" tab (opened first by default) scroll down to "GitHub Pages".
Here we select the master branch as the source, and / docs as the folder (you can also use the / root, but I prefer to keep the minimum number of files in the project root). Click "Save".
The "Theme Chooser" button opens a gallery of templates, where each can be poked, viewed and selected by clicking on the green "Select theme" button.
After choosing a theme, we will be thrown into the web editor, where it is proposed to edit the Markdown file, which will then become the site. Here you can describe everything your heart desires: from a simple presentation of yourself to the goals of the document and the features of the work.
Once you're happy with the content, commit your changes.
Where is my page?
The link to the assembled page is always stored in Settings -> GitHub Pages. It is better to register it in the Website of the repository (the gear next to the "About" field on the main page) so as not to lose it.
Downloading the latest release
There is a little trick: the latest release and all its files can always be referenced by replacing the commit tag in the URL with "latest". In our example, to get the my_asset_name.pdf file from the latest release, we need to insert a link
https://github.com/<your_username>/<repo_name>/releases/latest/download/my_asset_name.pdf.
In my case it was: https://github.com/alekseik1/github_actions_latex_template/releases/latest/download/my_asset_name.pdf .
After these steps, GitHub Pages always link to the latest release.
Outcome
We set up GitHub Actions to automatically build a pdf file, put it into release, and brought up a site on GitHub Pages containing the most recent version. The final version of the project can be found here .
Thank you for attention!