GitHub Pages

Зачем нужно

GitHub Pages — бесплатный хостинг статических сайтов прямо из GitHub-репозитория. Идеально для портфолио, документации и учебных проектов. Никаких серверов, никаких оплат — push в репозиторий и сайт доступен по username.github.io.

Где используется

  • Портфолио — username.github.io
  • Проектные сайты — username.github.io/project-name
  • Документация — техническая документация проекта
  • RS School — деплой заданий для ревью
  • Резюме — онлайн-версия CV

Два типа сайтов

User/Organization Site

Репозиторий: username.github.io
URL:         https://username.github.io
Ветка:       main
Лимит:       1 на аккаунт

Project Site

Репозиторий: любое-имя
URL:         https://username.github.io/repo-name
Ветка:       gh-pages или main (настраивается)
Лимит:       неограниченно

Настройка через gh-pages ветку

Вариант 1: ручной деплой

# Установи пакет gh-pages
npm install --save-dev gh-pages

# Добавь скрипт в package.json
# "scripts": { "deploy": "gh-pages -d dist" }

# Собери и задеплой
npm run build
npm run deploy

// package.json
{
  "homepage": "https://username.github.io/repo-name",
  "scripts": {
    "build": "vite build",
    "deploy": "gh-pages -d dist"
  },
  "devDependencies": {
    "gh-pages": "^6.0.0"
  }
}

Вариант 2: из настроек репозитория

  1. Repository → Settings → Pages
  2. Source: Deploy from a branch
  3. Branch: main (или gh-pages) / folder: / (root) или /docs
  4. Save → сайт будет доступен через минуту

Деплой через GitHub Actions

Workflow для Vite/React

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci
      - run: npm run build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Настройка в Settings

  1. Settings → Pages → Source: GitHub Actions
  2. Push workflow файл в .github/workflows/

Настройка base path для SPA

При деплое проекта в подпапку (username.github.io/repo-name) нужно настроить base path.

Vite

// vite.config.js
export default defineConfig({
  base: '/repo-name/',
  // ...
});

React Router

<BrowserRouter basename="/repo-name">
  <Routes>
    <Route path="/" element={<Home />} />
  </Routes>
</BrowserRouter>

Vue Router

const router = createRouter({
  history: createWebHistory('/repo-name/'),
  routes,
});

SPA — обработка роутов

GitHub Pages не поддерживает серверные роуты. При обновлении страницы /about будет 404.

Решение: 404.html hack

<!-- public/404.html -->
<!DOCTYPE html>
<html>
<head>
  <script>
    // Перенаправляем на index.html с сохранением пути
    const path = window.location.pathname;
    const repo = '/repo-name';
    if (path !== repo + '/' && path !== repo) {
      sessionStorage.setItem('redirect', path);
      window.location.replace(repo + '/');
    }
  </script>
</head>
<body></body>
</html>

<!-- В index.html добавить скрипт -->
<script>
  const redirect = sessionStorage.getItem('redirect');
  if (redirect) {
    sessionStorage.removeItem('redirect');
    window.history.replaceState(null, '', redirect);
  }
</script>

Решение: HashRouter

// Используй HashRouter вместо BrowserRouter
import { HashRouter } from 'react-router-dom';

// URL будут вида: username.github.io/repo/#/about
<HashRouter>
  <Routes>
    <Route path="/" element={<Home />} />
    <Route path="/about" element={<About />} />
  </Routes>
</HashRouter>

Custom Domain

  1. Settings → Pages → Custom domain → ввести mysite.com
  2. Добавь DNS-записи у регистратора:
Type    Host    Value
A       @       185.199.108.153
A       @       185.199.109.153
A       @       185.199.110.153
A       @       185.199.111.153
CNAME   www     username.github.io
  1. Создай файл CNAME в корне publish directory:
mysite.com
  1. GitHub автоматически выпустит SSL-сертификат

Ограничения

Ограничение Значение
Размер репозитория до 1 GB рекомендовано
Bandwidth 100 GB/месяц
Сборки 10 сборок/час
Размер сайта до 1 GB
Серверный код Нет (только статика)
Приватные репо Только Pro/Team/Enterprise

Частые ошибки

Ошибка Проблема Решение
404 на подстраницах SPA routing Используй 404.html hack или HashRouter
Пустая страница Неправильный base path Добавь base: '/repo-name/' в конфиг
CSS/JS не загружается Пути без base Используй относительные пути или base
Сайт не обновляется Кэш Подожди 1-2 мин, hard refresh (Ctrl+Shift+R)
Actions деплой fails Нет permissions Добавь pages: write в workflow

Практика

  1. Создай репозиторий username.github.io и задеплой HTML-страницу
  2. Задеплой Vite-проект через gh-pages пакет
  3. Настрой автодеплой через GitHub Actions
  4. Реши проблему SPA-routing для React Router
  5. Добавь CNAME для кастомного домена

Связанные темы

Ресурсы