Русский
Русский
English
Статистика
Реклама

Github pages

Из песочницы GitHub Actions и LaTeX поднимаем, заливаем

22.08.2020 14:05:15 | Автор: admin
В этой статье мы настроим пайплайн в 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 Pageson: pushjobs:build:# Базовая ОС, на которой будут исполняться команды. Оставим ubunturuns-on: ubuntu-lateststeps:# Необходимо использовать этот action, чтобы получить содержимое репо- uses: actions/checkout@v2# Компилируем документ- name: Build documentuses: xu-cheng/latex-action@v2with:# Переименуйте, если у вас другой файлroot_file: main.tex# Больше параметров в офф. документацииworking_directory: latex_sources/# Аргументы, к которыми запускать компилятор (latexmk)# -jobname=<name> дает возможность поменять имя выходного файлаargs: -jobname=my_doc -pdf -file-line-error -halt-on-error -interaction=nonstopmodecompiler: latexmk# Загружаем собранные pdf-файлы- name: Upload pdf documentuses: actions/upload-artifact@v2with:# Это значение используется как ключ в хранилищеname: my_doc# Путь до собранного pdf. Может содержать *, **# Здесь это <working_directory>/<jobname>.pdfpath: 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 используется внутренне: по нему можно ссылаться на результаты из другого stepid: 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 artifactsuses: actions/download-artifact@v2with:# Тот самый ключ, который мы указывали в upload-artifactname: my_doc- name: Create Releaseuses: actions/create-release@v1id: create_releaseenv:# По офф.документации, надо указать GITHUB_TOKENGITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actionswith:# Берем результат из 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 }})# Наш релиз не набросок и не пререлиз, так что оба в falsedraft: falseprerelease: false# Прикладываемые файлы надо заливать отдельным step- name: Upload pdf assetuses: actions/upload-release-asset@v1env:# Тоже требуется токен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.pdfasset_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, содержащий самую свежую версию. Финальную версию проекта можно найти здесь.

Спасибо за внимание!
Подробнее..
Категории: Ci/cd , Github , Github actions , Latex , Github pages

Категории

Последние комментарии

  • Имя: Макс
    24.08.2022 | 11:28
    Я разраб в IT компании, работаю на арбитражную команду. Мы работаем с приламы и сайтами, при работе замечаются постоянные баны и лаги. Пацаны посоветовали сервис по анализу исходного кода,https://app Подробнее..
  • Имя: 9055410337
    20.08.2022 | 17:41
    поможем пишите в телеграм Подробнее..
  • Имя: sabbat
    17.08.2022 | 20:42
    Охренеть.. это просто шикарная статья, феноменально круто. Большое спасибо за разбор! Надеюсь как-нибудь с тобой связаться для обсуждений чего-либо) Подробнее..
  • Имя: Мария
    09.08.2022 | 14:44
    Добрый день. Если обладаете такой информацией, то подскажите, пожалуйста, где можно найти много-много материала по Yggdrasil и его уязвимостях для написания диплома? Благодарю. Подробнее..
© 2006-2024, personeltest.ru