GitHub Pages (гитхаб пейджес): бесплатный хостинг сайта — как опубликовать пошагово

Что такое GitHub Pages

GitHub Pages — это бесплатный хостинг статических сайтов, встроенный в GitHub. Вы храните файлы сайта в обычном Git-репозитории, а GitHub сам раздаёт их по HTTPS. Каждый новый git push в нужную ветку обновляет сайт, поэтому отдельного FTP, панели хостинга и ручной заливки файлов не нужно.

В русскоязычном поиске сервис называют по-разному: «гитхаб пейджес», «гитхаб пейдж», «гитхаб pages», иногда просто «гитхаб хостинг». Встречается и запрос «git pages что это» — но правильно говорить именно GitHub Pages: это функция платформы GitHub, а не самого Git. Сам Git ничего не публикует, он только хранит историю изменений.

Чаще всего на GitHub Pages размещают документацию к проектам, личные страницы и портфолио, блоги, лендинги, учебные проекты и демо фронтенд-приложений на React, Vue или Svelte после сборки.

Git pages — это хостинг для статики

Ключевое слово — статический. GitHub Pages отдаёт браузеру готовые файлы: HTML, CSS, JavaScript, картинки, шрифты, JSON. Выполнять код на сервере он не умеет: PHP, Python, Node.js на стороне сервера и базы данных здесь не работают. Если сайту нужна регистрация, корзина или админка с базой данных, понадобится обычный хостинг или облачная платформа.

При этом JavaScript в браузере работает как обычно. Одностраничное приложение может обращаться к внешним API, формы можно отправлять через сторонние сервисы, а поиск по сайту — делать на клиенте.

Какие бывают сайты на GitHub Pages

У GitHub Pages три типа сайтов, и от типа зависит адрес.

Сайт пользователя или организации может быть только один на аккаунт, а сайтов проектов — сколько угодно, по одному на репозиторий. Имя репозитория для личного сайта должно точно совпадать с вашим логином на GitHub: если логин ivan-petrov, репозиторий называется ivan-petrov.github.io.

Для публичных репозиториев Pages доступен на бесплатном тарифе. Публиковать сайт из приватного репозитория можно на платных тарифах GitHub; сам опубликованный сайт при этом всё равно виден всем в интернете.

Как опубликовать сайт на GitHub Pages пошагово

Разберём самый простой путь: готовые HTML-файлы, публикация из ветки. Понадобится аккаунт на GitHub и установленный Git.

Шаг 1. Создайте репозиторий

На GitHub создайте новый публичный репозиторий. Для личного сайта назовите его username.github.io, для сайта проекта — как угодно. Затем склонируйте его и добавьте главную страницу:

git clone https://github.com/username/username.github.io.git
cd username.github.io
echo "<h1>Привет, GitHub Pages</h1>" > index.html

Главная страница обязательно называется index.html (или index.md, или README.md — их GitHub тоже превратит в главную). Регистр важен: Index.html не подойдёт.

Шаг 2. Отправьте файлы на GitHub

git add index.html
git commit -m "Первая страница сайта"
git push origin main

Если вы впервые отправляете изменения и Git просит логин и пароль, используйте персональный токен доступа или вход через браузер — обычный пароль от аккаунта GitHub для git push по HTTPS не принимает.

Шаг 3. Включите Pages в настройках

Откройте репозиторий на GitHub, перейдите в Settings и в боковом меню выберите Pages. В блоке Build and deployment в поле Source выберите Deploy from a branch. Ниже укажите ветку (обычно main) и папку: корень / (root) или /docs. Нажмите Save.

Папка /docs удобна, когда в репозитории лежит код проекта, а сайт с документацией — рядом, в отдельном каталоге.

Шаг 4. Дождитесь публикации

Публикация занимает от нескольких секунд до нескольких минут; GitHub предупреждает, что первая может идти до 10 минут. Ход сборки видно на вкладке Actions: там появится процесс pages build and deployment. Когда он завершится зелёной галочкой, на странице Settings → Pages появится адрес сайта.

Дальше всё просто: правите файлы, делаете коммит и git push — сайт обновляется сам.

Публикация через GitHub Actions

Публикация из ветки подходит, когда в репозитории лежат готовые файлы. Если же сайт нужно сначала собрать — например, это приложение на Vite, React или генератор вроде Hugo, — удобнее источник GitHub Actions. В Settings → Pages в поле Source выберите GitHub Actions, и GitHub предложит готовые шаблоны workflow.

Минимальный workflow для статических файлов из папки dist после сборки выглядит так:

name: Deploy to Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v4

Файл кладётся в .github/workflows/pages.yml. После git push Actions установит зависимости, соберёт проект и выложит содержимое dist. Плюс подхода — в репозитории хранится только исходный код, а собранные файлы не засоряют историю коммитов.

Частая ловушка сайтов проектов — пути. Сайт открывается по адресу /имя-репозитория/, а сборщик по умолчанию ссылается на ресурсы от корня /. В результате страница грузится без стилей и скриптов. Лечится настройкой базового пути: в Vite — параметр base: '/имя-репозитория/', в других сборщиках — аналогичная опция.

Jekyll и генераторы статических сайтов

При публикации из ветки GitHub по умолчанию прогоняет файлы через Jekyll — генератор статических сайтов на Ruby. Поэтому можно писать страницы в Markdown, подключать темы и шаблоны, а GitHub сам превратит их в HTML. Для блога или документации это удобно: пишете файлы .md, а оформление берёт тема.

Побочный эффект: Jekyll игнорирует файлы и папки, имя которых начинается с подчёркивания, например _next или _assets. Если сайт собран другим инструментом и такие папки нужны, положите в корень пустой файл .nojekyll:

touch .nojekyll
git add .nojekyll
git commit -m "Отключить Jekyll"
git push

Другие генераторы — Hugo, Astro, Eleventy, MkDocs, Docusaurus — работают через GitHub Actions: сборка в workflow, публикация готовой папки. Сам GitHub Pages про них ничего не знает, ему достаточно итоговых файлов.

Как подключить свой домен к GitHub Pages

Адрес username.github.io подходит для учебных проектов, но для портфолио или проекта лучше свой домен. Подключение идёт в две стороны: у регистратора домена и в настройках репозитория.

Настройка DNS

Для поддомена вроде www.example.com или blog.example.com создайте запись CNAME, которая указывает на username.github.io. Для корневого домена example.com создайте A-записи на IP-адреса GitHub Pages:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Актуальный список адресов, включая IPv6 для записей AAAA, есть в документации GitHub — сверяйтесь с ней перед настройкой. Лучше настроить и корневой домен, и www: тогда GitHub будет перенаправлять один адрес на другой.

Настройка в репозитории

В Settings → Pages впишите домен в поле Custom domain и сохраните. При публикации из ветки GitHub создаст в репозитории файл CNAME с именем домена. При публикации через Actions файл CNAME не нужен, домен хранится в настройках.

GitHub рекомендует подтвердить домен в настройках аккаунта (раздел Pages в настройках профиля): это защищает от ситуации, когда кто-то другой привяжет ваш домен к своему репозиторию, пока DNS указывает на GitHub. Изменения DNS расходятся до суток, так что если домен сразу не заработал — подождите.

HTTPS на GitHub Pages

Для адресов *.github.io HTTPS включён всегда. Для своего домена GitHub сам выпускает сертификат Let's Encrypt, когда DNS настроен правильно. После этого в Settings → Pages станет доступна галочка Enforce HTTPS — включите её, чтобы все запросы по HTTP перенаправлялись на HTTPS.

Если галочка неактивна, значит, сертификат ещё не выпущен: проверьте DNS-записи и подождите. Иногда помогает удалить домен из поля Custom domain и добавить заново — это запускает повторный выпуск сертификата. Отдельно проверьте, что сайт не загружает картинки и скрипты по http://: браузер заблокирует такие ресурсы как смешанное содержимое.

Ограничения GitHub Pages

Хостинг бесплатный, но у него есть рамки. Они описаны в документации GitHub, и для большинства личных и учебных сайтов их хватает с запасом.

Кроме технических лимитов есть правила использования: GitHub Pages не предназначен для коммерческих сервисов вроде интернет-магазинов и SaaS, а также для раздачи больших файлов. Для портфолио, документации, блога и лендинга проекта — пожалуйста.

Ещё одно ограничение — нет серверной настройки. Своих редиректов, заголовков ответа и правил вроде .htaccess здесь нет. Можно лишь положить собственную страницу 404.html в корень — GitHub будет показывать её для несуществующих адресов.

Типичные проблемы и как их решить

Ошибка 404 на GitHub Pages

Самая частая причина — нет файла index.html в той папке, которая выбрана источником. Проверьте, что выбрали правильную ветку и папку (/ (root) или /docs), а файл называется именно index.html в нижнем регистре. Вторая причина — сайт ещё не опубликован: загляните на вкладку Actions и дождитесь окончания сборки.

Если 404 появляется на внутренних страницах одностраничного приложения при обновлении страницы, дело в маршрутизации: сервер не знает адрес /about, потому что такого файла нет. Обходные пути — hash-маршрутизация (/#/about) или копия index.html под именем 404.html.

Сайт не обновляется

Сначала убедитесь, что изменения действительно попали на GitHub: выполните git status и git log origin/main --oneline -3. Затем откройте вкладку Actions: если сборка упала, там будет красный крестик и лог с ошибкой — например, синтаксис в файле Jekyll или ошибка в workflow.

Если сборка прошла, а в браузере старая версия, виноват кэш. GitHub Pages кэширует файлы на несколько минут, плюс кэширует браузер. Обновите страницу с очисткой кэша (Ctrl+F5 или Cmd+Shift+R) или откройте её в приватном окне.

Стили и картинки не загружаются

Почти всегда — неверные пути. На сайте проекта ссылка /style.css ведёт в корень username.github.io, а не в папку репозитория. Используйте относительные пути (style.css, ./img/logo.png) или задайте базовый путь в сборщике. Также проверьте регистр имён: серверы GitHub различают Logo.PNG и logo.png, хотя на Windows локально всё работало.

Пропали папки с подчёркиванием

Это Jekyll: он не публикует каталоги вида _app. Добавьте в корень файл .nojekyll или переключитесь на публикацию через GitHub Actions.

Итог

Гитхаб пейджес — самый быстрый способ бесплатно выложить статический сайт: репозиторий, файл index.html, источник в Settings → Pages — и через пару минут сайт открыт по адресу username.github.io. Для сайтов со сборкой используйте GitHub Actions, для своего домена — записи DNS и галочку Enforce HTTPS. Помните про границы: только статика, без серверного кода и с лимитами на размер и трафик. Работа с GitHub, отправка изменений и автоматизация разобраны на практике в курсе по Git.