Публикация Pages через workflow

Info

GitVerse Pages поддерживает публикацию сайтов через пользовательские workflow.
Вы создаете обычный workflow в .gitverse/workflows, описываете шаги сборки сайта, а публикацию и деплой делаете с помощью специальных экшенов от GitVerse.

Публикация через workflow позволяет полностью управлять процессом: вы самостоятельно определяете окружение, зависимости и шаги сборки.

Ключевое условие: результатом сборки должен быть каталог со статикой для сайта, который будет опубликован как Pages.

Когда стоит выбирать собственный workflow

Используйте собственный workflow, если:

  • вы не используете Jekyll (например, Hugo/Astro/Docusaurus/MkDocs/VitePress и т.п.);
  • вам нужны кастомные версии Node.js/Go/Python/Ruby или дополнительные пакеты;
  • сборка требует дополнительных шагов (генерация API-доков, копирование ассетов, постобработка HTML);
  • директория со статикой отличается от стандартной и ее нужно явно задать.

Если у вас простой сайт на HTML или стандартный Jekyll без особых требований — быстрее стартовать с шаблона.

Включение настраиваемых workflow

Чтобы начать использовать настраиваемые workflow:

  1. Откройте настройки репозитория: Настройки → Страницы.

  2. Включите функциональность соответствующим тумблером.

  3. В поле Источник выберите Воркфлоу.

  4. Выберите шаблон, нажмите Использовать или создайте собственный workflow.

  5. Запустите workflow (вручную или дождитесь автоматического запуска при событии, которое вы настроили).

Warning

После переключения источника на Воркфлоу публикация сайта зависит только от запусков workflow. Если workflow не запускается или падает — сайт не обновится.

Использование шаблонов

Шаблоны — это готовые workflow, которые создают рабочую конфигурацию публикации без настройки с нуля. Их можно использовать «как есть» или доработать под свой проект.

Примеры шаблонов

Simple HTML Page подходит для статического сайта без этапа сборки (HTML/CSS/JS). Вы просто добавляете файлы в репозиторий, а workflow упаковывает их и публикует.

Jekyll подходит для сайтов на Jekyll (Markdown, Liquid, темы). Workflow выполнит сборку и опубликует результат.

Выберите подходящий шаблон — и вы сразу получите рабочую конфигурацию для публикации.

С полным списком шаблонов вы можете ознакомиться в репозитории шаблонов.

Использование собственных workflow

Если шаблоны не покрывают ваши требования, создайте собственный workflow в репозитории и опишите в нем шаги сборки и публикации.

Обычно workflow размещается в каталоге .gitverse/workflows

Типовой pipeline состоит из двух частей:

  1. Build — установка зависимостей и сборка, результатом которой становится каталог со статикой.
  2. Deploy — публикация собранной статики в GitVerse Pages.

Обязательные требования к публикации

Выберите источник публикации

Для публикации Pages через собственный workflow выберите в настройках источник Воркфлоу. В ином случае при выполнении workflow, экшен deploy-pages будет возвращать ошибку.

Используйте официальные экшены для Pages

Для передачи результата сборки и публикации необходимо использовать:

  • upload-pages-artifact — загрузка каталога со статическими файлами;
  • deploy-pages — размещение сайта на основе загруженных файлов.

В артефакте должен быть index.html

Загружаемый артефакт должен содержать файл index.html. Он является входной точкой сайта, и маршрутизация GitVerse Pages строится вокруг него.

Если проект не предполагает ручного создания HTML-страниц (например, SPA), файл index.html все равно требуется — обычно его генерирует сборщик.

Указывайте, где лежит статика

По умолчанию экшн upload-pages-artifact ожидает статические файлы в каталоге _site.

  • если вы используете другой каталог (например, dist, build), явно укажите путь через параметр path;
  • убедитесь, что именно этот каталог содержит index.html.

Правильно: вы загружаете каталог со статикой. Неправильно: вы загружаете исходники проекта и надеетесь, что оно «само соберется».

Меняйте параметр retention-days только в крайнем случае

Увеличение срока хранения может:

  • израсходовать лимиты бесплатного/базового тарифа хранения артефактов (free tier);
  • привести к исчерпанию доступного объема хранилища для артефактов;
  • в итоге вызвать проблемы с публикацией.

Минимальный пример workflow

Ниже пример workflow, который:

  • для примера создает _site/index.html;
  • загружает содержимое _site как артефакт;
  • публикует сайт.
name: Publish Pages
 
on:
  push:
    branches: [ "master" ]
  workflow_dispatch:
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      # Замените этот шаг на сборку вашего генератора статики
      - name: Build site
        run: |
          mkdir -p _site
          echo "<h1>Hello, GitVerse Pages</h1>" > _site/index.html
 
      - name: Upload pages artifact
        uses: gitverse/upload-pages-artifact@v1.0.0
        with:
          path: _site
 
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        uses: gitverse/deploy-pages@v1.0.0

Info

Если ваш генератор кладет результат не в _site, измените path. Например: path: dist или path: build.

Примеры для популярных сценариев

Сборка Node.js (например, Astro/VitePress и.т.д)

Пример: сборщик генерирует статику в dist вместо стандартного каталога _site

name: Publish Pages (Node)
 
on:
  push:
    branches: [ "master" ]
  workflow_dispatch:
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
 
      - name: Install
        run: npm ci
 
      - name: Build
        run: npm run build
 
      - name: Upload pages artifact
        uses: gitverse/upload-pages-artifact@v1.0.0
        with:
          path: dist
 
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: gitverse/deploy-pages@v1.0.0

Публикация «как есть» (без сборки)

Если вы храните готовые HTML-файлы в репозитории (например, в каталоге public):

name: Publish Pages (No build)
 
on:
  push:
    branches: [ "master" ]
  workflow_dispatch:
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Verify entrypoint
        run: test -f public/index.html
 
      - name: Upload pages artifact
        uses: gitverse/upload-pages-artifact@v1.0.0
        with:
          path: public
 
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: gitverse/deploy-pages@v1.0.0

Частые проблемы и как их быстро диагностировать

Сайт опубликовался, но отдает 404

  • проверьте, что в артефакте есть index.html в корне загружаемого каталога;
  • убедитесь, что вы загрузили именно каталог со статикой, а не корень репозитория.

Workflow прошел, но сайт не обновился

  • проверьте, что выбран источник Воркфлоу в настройках Pages;
  • убедитесь, что выполняется job с deploy-pages.

upload-pages-artifact не находит файлы

  • проверьте path;
  • выведите список файлов указанного каталога в path перед загрузкой: 
    ls -la
ls -la _site || true
ls -la dist || true

Неожиданно растет потребление хранилища

  • проверьте, что retention-days: 1 не изменен;
  • проверьте размер каталога со статикой (быть может, есть артефакты сборки, которые не должны попадать в публикацию).

Что важно запомнить

При публикации Pages через workflow вы самостоятельно определяете шаги сборки и окружение. Вы можете использовать любые инструменты и сценарии — главное, чтобы workflow в итоге загрузил корректный каталог со статикой и затем выполнил деплой через проверенные экшены.

Вид графа

Связанные страницы