0034 — Github Actions для Hugo

Зачем?

Всё, что можно автоматизировать, нужно автоматизировать. Снижение человеческого фактора как правило всегда идёт на пользу.

Ну и делать лишние действия тоже не хочется. Почему бы не заставить машину делать то, что вынужден делать сам?

Теперь при создании PR в ветку main этого репозитория выполняется проверка корректности обновлённого кода. Если со сборкой есть проблемы, PR будет заблокирован.

Если PR успешен, то при слиянии с main будет выполнена автоматическая сборка проекта и его выкладка на хостинг. Удобно? Не то слово!

Подготовка к работе

Считаем, что проект у вас уже есть и размещается на GitHub.

1. Создайте в корне проекта подкаталог .github/workflows/:

   mkdir -p .github/workflows/
   

2. Создайте ключ SSH, который будет использоваться для деплоя на сервер с помощью rsync:

   ssh-keygen -t ed25519 -N "" -f ~/.ssh/<hosting> -C "GitHub Actions Deploy Key"
   

   Здесь:

   • -t ed25519 — генерация ключа с помощью алгоритма ED25519.

     В настоящее время этот алгоритм считается достаточно надёжным.

   • -N "" — создание ключа без парольной защиты.

     Ключ будет использоваться в автоматическом режиме, поэтому парольная защита снимается. Наверное, можно как-то передать ключ через переменные окружения и GitHub Secrets, но я пока не разбирался.

   • -f ~/.ssh/<hosting> — имя файла, в который будет сохранён ключ. На самом деле в каталоге ~/.ssh/ будет создано два файла со следующими именами:

     • <hosting> — приватная часть ключа;
     • <hosting>.pub — публичная часть ключа.

   • -C "GitHub Actions Deploy Key" — необязательный комментарий к ключу. Тем не менее, стоит добавить — указанное в этом поле значение можно увидеть в журнале подключения к серверу по SSH.

3. Перейдите на страницу репозитория на GitHub.

4. Выберите вкладку Settings.

5. Разверните раздел Secrets and variables.

6. Выберите раздел Actions.

7. Используйте кнопку New repository secret для создания секретов.

   В моём случае понадобились следующие секреты:

   • FOLDER — путь к каталогу на сервере;
   • HOST — адрес хоста, на который выкладывается сайт;
   • SSH_KEY — приватная часть ключа SSH, с помощью которого можно подключаться к серверу;
   • USER — имя пользователя, используемого для подключения к серверу по SSH.

8. Во вкладке Variables создайте переменную HUGO_VERSION со значением 0.120.3.

   Актуальную версию уточняйте на странице релизов Hugo.

9. Разместите публичную часть ключа SSH на целевом сервере.

   Тут я вам не помощник — читайте документацию используемого хостинга. Как правило, достаточно добавить содержимое файла key.pub в файл ~/.ssh/authorized_keys.

Настройка тестирования

Настройку тестирования делал исходя из того, что PR'ы в main не должны ничего там сломать. Если тестирование не проходит, PR не может быть влит.

В итоге получился такой файл:

---
name: Testing

on:
  pull_request:

jobs:
  Testing:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Update APT index
        run: sudo apt-get update

      - name: Install DEB packages
        run: sudo apt-get install ruby python3-pip --yes

      - name: Install AsciiDoctor
        run: sudo gem install asciidoctor

      - name: Install rst2html
        run: sudo pip3 install rst2html

      - name: Install Hugo
        run : |
          wget https://github.com/gohugoio/hugo/releases/download/v${{ vars.HUGO_VERSION }}/hugo_${{ vars. HUGO_VERSION}}_linux-amd64.deb
          sudo dpkg -i hugo_${{ vars.HUGO_VERSION}}_linux-amd64.deb

      - name: Build Project
        run: hugo --panic-on-warning

Что тут вообще происходит?

Action называется Testing и срабатывает в случае создания PR. Используемая версия Hugo задана в переменной HUGO_VERSION. Процесс тестирования состоит из нескольких этапов, рассмотрим их подробнее.

- name: Checkout code
  uses: actions/checkout@v4
  with:
    submodules: recursive

sudo apt-get update

Настройка сборки

Для сборки и выкладки сайта на сервер используется файл deploy.yml. В нём описана задача Build and deploy.

Привожу содержимое файла целиком, но в описании шагов расскажу только про отличия в сравнении с testing.yml.

---
name: Build and deploy

on:
  push:
    branches:
      - 'main'

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Update APT index
        run: sudo apt-get update

      - name: Install DEB packages
        run: sudo apt-get install openssh-client ruby python3-pip --yes

      - name: Install AsciiDoctor
        run: sudo gem install asciidoctor

      - name: Install rst2html
        run: sudo pip3 install rst2html

      - name: Install Hugo
        run : |
          wget https://github.com/gohugoio/hugo/releases/download/v${{ vars.HUGO_VERSION }}/hugo_${{ vars.HUGO_VERSION }}_linux-amd64.deb
          sudo dpkg -i hugo_${{ vars.HUGO_VERSION }}_linux-amd64.deb

      - name: Build project
          run: hugo --minify --panic-on-warning

      - name: Set SSH settings
        run: |
          mkdir -p ~/.ssh/
          echo "${{ secrets.SSH_KEY }}" > ~/.ssh/private.key
          chmod 600 ~/.ssh/private.key
          ssh-keyscan ${{ secrets.HOST }} >> ~/.ssh/known_hosts

      - name: Deploy files to server
        run: |
          eval $(ssh-agent -s)
          ssh-add ~/.ssh/private.key
          rsync --delete --quiet -e ssh --recursive --dirs --verbose ./public/* ${{ secrets.USER }}@${{ secrets.HOST }}:${{ secrets.FOLDER }}
          rsync --delete --quiet -e ssh --recursive --dirs --verbose .htaccess ${{ secrets.USER }}@${{ secrets.HOST }}:${{ secrets.FOLDER }}

Особенности

1. Выполняемая здесь задача срабатывает только при push в ветку main.
2. При сборке сайта используется сжатие того, что можно сжать — HTML, JS, CSS.
3. Для выкладки сайта на хостинг используется rsync.