В этой статье мы настроим пайплайн в GitHub для автоматической сборки pdf-файлов и последующей выкладки в Releases. Также поднимаем небольшой сайт-визитку с ссылкой на самые свежие сборки.

Материал будет полезен новичкам и тем, кто хочет быстро поднять CI/CD для latex встренными средствами GitHub.

Вступление

Просматривая на днях репозиторий со своим CV (я делаю его в latex, благо, есть много шаблонов), я подумал, что было бы неплохо организовать некое единое место, где всегда лежит актуальная версия документа.

Основные требования были просты:

1. Минимальными усилиями поднять сайт с релизами;
2. Сделать обновления контента на сайте автоматическим.

В голове нарисовалось решение в виде пайплайна:

1. Push коммита на GitHub;
2. Сборка .tex-файлов в CI/CD;
3. Отправка собранных pdf в GitHub releases;
4. Обновление pdf-файлов на сайте-визитке.

В этой статье мы рассмотрим подробнее каждый шаг. В качестве сайта будет использоваться GitHub Pages. Для CI/CD будем использовать GitHub Actions.

Нам понадобится:

• Аккаунт на GitHub;
• Инструменты для компиляции LaTeX;
• Любой текстовой редактор (я использую VIM, настроенный на latex);

Поехали!

Подключаем GitHub Actions

Здесь все действия можно выполнить с сайта, не прибегая к консоли.

Заходим в «Actions» (подчеркнуто красным).

и находим там карточку «Simple workflow», где нажимаем кнопку «Set up this workflow»

Перед нами откроется редактор с шаблоном workflow. На этом моменте стоит остановиться поподробнее.

GitHub Actions работает с Workflow, которые описываются в отдельных файлах. Каждый workflow состоит из:

1. Имени (секция name: …);
2. Условия запуска (секция on: …);
3. Списка задач на выполнение (секция jobs: …)

Каждая задача (job) тоже состоит из кусков поменьше, называемых step. Каждый step — это атомарное действие (выполняемое полностью за раз). При этом step имеет свое имя (name: …) и список команд (run: …), а также может использовать уже готовый action (uses: …) от сторонних разработчиков.

Сторонние actions — это самая мощная часть GitHub Actions. Они могут делать многие вещи: устанавливать JDK, запускать python-тесты в tox и многое другое. В данном мануале мы будем использовать xu-cheng/latex-action@v2 для компиляции latex (с ним не возникло проблем с кириллицей) и actions/upload-artifact@v2 для загрузки артефактов.

Вернемся к нашему редактору. Предложенный шаблон можно подправить, приведя его к виду:

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  

Сохраните это в файл, название файла выберете любым (можно latex.yml). После того как закоммитите создание файла в веб-редакторы, на GitHub Actions должен должна пойти первая сборка, по результатам которой появится артефакт — собранный pdf.

Ура! Теперь можно приступать к релизам.

Настраиваем автоматические релизы

Система релизов в GitHub имеет одну особенность: релиз всегда привязан к коммиту с тэгом. Поэтому у нас есть два варианта:

1. Ставить тэги вручную на те коммиты, по которым мы хотим собирать и релизить pdf-файлы;
2. Ставить теги в автоматическом режиме на все коммиты и релизить их.

Для меня второй вариант показался более удобным, т.к. я обычно делаю коммит и пуш именно тогда, когда работа завершена (либо логически, либо на сегодняшний день). Поэтому в дальнейшем я буду рассказывать про него.

Для создания релиза мы будем использовать действие actions/create-release@v1 и для загрузки pdf-файла в созданный релиз (да, он загружается отдельно) используем actions/upload-release-asset@v1.

Добавим новый 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  

Добавляем в файл workflow, коммитим изменения. Идем в Actions и видим, что добавилась еще один шаг:

При этом в releases тоже появлся собранный pdf.

Осталось дело за малым — залить на сайт.

Поднимаем GitHub Pages

GitHub предоставляет возможность для каждого проекта создавать веб-страницу и дает бесплатный хостинг на нее. Но совершенно не обязательно владеть JS/CSS/HTML, чтобы написать что-то стоящее! Из коробки сервис предлагает несколько симпатичных шаблонов, которые полностью решают вопрос с версткой. От вас потребуется только заполнить Markdown-документ, а система сделает все остальное.

Идем в раздел «Settings» репозитория и во вкладке «Options» (открывается первой по-умолчанию) листаем вниз до «GitHub Pages».

Тут в качестве source выбираем ветку master, а в качестве папки — /docs (можно и корень /, но я предпочитаю держать минимальное количество файлов в корне проекта). Нажимаем «Save».

Кнопкой «Theme Chooser» открывается галерея шаблонов, где каждый можно потыкать, посмотреть и выбрать нажатием на зеленую кнопку «Select theme».

После выбора темы нас бросит в веб-редактор, где предлагается отредактировать Markdown-файл, который потом станет сайтом. Здесь можно описать все, что душе угодно: от простого представления себя до целей документа и особенностей работы.

Как только вы будете довольны содержимым, закоммитьте изменения.

Где моя страница?

Ссылка на собранную страницу всегда хранится в «Settings» -> «GitHub Pages». Её лучше прописать в Website репозитория (шестеренка возле поля «About» на главной странице), чтобы не потерять.

Загружаем свежайший релиз

Есть небольшая хитрость: на последний релиз и все его файлы всегда можно сослаться, заменив тег коммита в URL на «latest». В нашем примере, чтобы получить файл my_asset_name.pdf из последнего релиза, нужно вставить ссылку https://github.com/<your_username>/<repo_name>/releases/latest/download/my_asset_name.pdf.

В моем случае это было: https://github.com/alekseik1/github_actions_latex_template/releases/latest/download/my_asset_name.pdf.

После этих действий GitHub Pages всегда ссылаются на последний релиз.

Итоги

Мы настроили GitHub Actions на автоматическую сборку pdf-файла, выкладывание в релиз и подняли сайт на GitHub Pages, содержащий самую свежую версию. Финальную версию проекта можно найти здесь.

Спасибо за внимание!