Руководство по включению Pages

Это руководство проводит apothem.ahmedgad.com от свежей конфигурации GitHub Pages до целевой HTTPS-страницы со статусом 200 OK. Процедура написана для оператора, владеющего gh и консолью DNS-провайдера; компетентный новый участник следует ей без предварительного контекста.

Руководство построено как независимое от провайдера ядро (шаги на стороне GitHub и шаги с DNS-записями, общие для каждого провайдера), за которым следуют специфичные для провайдера приложения для Namecheap, Cloudflare, Route53 и универсальный DNS-вариант на крайний случай. Выполняйте ядро по порядку; перейдите к приложению, соответствующему регистратору домена верхнего уровня / DNS-хосту; вернитесь к ядру для проверки.

Сайт размещается из публичного репозитория ahmed-g-gad/apothem через GitHub Pages, при этом CNAME пользовательского домена указывает на ahmed-g-gad.github.io. Сборка статического сайта выводится в site/dist/; рабочий процесс Pages переносит этот артефакт сборки на живой сайт при каждом push в main.

1. Предварительные условия

Оператор подтверждает следующее перед началом:

• Состояние репозитория. ahmed-g-gad/apothem публичен, имеет включённые Pages (Settings > Pages > Source: GitHub Actions), а рабочий процесс publish-static-site.yml существует по пути .github/workflows/publish-static-site.yml.
• Полномочия на DNS. Оператор управляет DNS для ahmedgad.com у регистратора или у делегированного DNS-хоста (Cloudflare, Route53 и т. д.). DNS-хост определяется через dig NS ahmedgad.com +short.
• Инструментарий. gh (GitHub CLI) версии 2.40 или новее, авторизованный в аккаунте ahmed-g-gad; dig (BIND dig или drill) для проверки DNS; браузер для инспекции HTTPS.
• Позиция по апексу. Это руководство настраивает только поддомен apothem.ahmedgad.com. Апекс ahmedgad.com не затрагивается. CNAME на апексе требует CNAME-уплощения (Cloudflare) или ALIAS-записей (Route53); путь через поддомен избегает обоих классов сложностей.

2. Независимое от провайдера ядро

2.1 Добавьте пользовательский домен в Pages

gh api -X PUT \
  /repos/ahmed-g-gad/apothem/pages \
  -F cname=apothem.ahmedgad.com \
  -F https_enforced=true

Проверьте, что вызов вернул новую CNAME-запись:

gh api /repos/ahmed-g-gad/apothem/pages \
  --jq '.cname, .https_enforced, .status'

Ожидаемый вывод:

apothem.ahmedgad.com
true
built

Статус built подтверждает, что самая недавняя сборка Pages прошла успешно. Статус null означает, что Pages не запускался с момента применения CNAME — отправьте пустой коммит в main, чтобы запустить сборку.

2.2 Подтвердите файл CNAME

GitHub Pages получает site/public/CNAME через артефакт сборки статического сайта при каждом развёртывании. Файл содержит пользовательский домен в одну строку, без схемы, без завершающего слеша:

apothem.ahmedgad.com

Файл расположен по пути site/public/CNAME. Проверьте:

cat site/public/CNAME

Если файл отсутствует, воссоздайте его по пути site/public/CNAME и закоммитьте под chore: restore Pages CNAME.

2.3 Добавьте DNS-запись

Pages обслуживает пользовательский домен, когда DNS-провайдер апекса возвращает один из четырёх IP-адресов GitHub (для апекс-доменов) или CNAME, указывающий на <owner>.github.io (для поддоменов). Для apothem.ahmedgad.com класс записи — CNAME:

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

2.4 Дождитесь распространения DNS

Распространение завершается в течение пяти минут для записей с низким TTL и в течение часа для TTL по умолчанию в 3600 секунд — граничные узлы провайдера могут продлить это окно во время передачи DNS-зоны. Отслеживайте прогресс:

dig apothem.ahmedgad.com CNAME +short

Ожидаемый вывод:

ahmed-g-gad.github.io.

Пустой вывод означает, что запись ещё не распространилась. Повторяйте каждые 30 секунд. Если запись так и не появляется через 30 минут, вернитесь к приложению, соответствующему DNS-хосту, и убедитесь, что запись зафиксирована у провайдера, а не находится в состоянии черновика.

2.5 Проверьте HTTPS

curl -sSI https://apothem.ahmedgad.com/ | head -5

Ожидаемый вывод:

HTTP/2 200
server: GitHub.com
content-type: text/html; charset=utf-8
strict-transport-security: max-age=31536000

Строки HTTP/2 200 и server: GitHub.com вместе подтверждают, что Pages обслуживает сайт под действующим TLS-сертификатом. Ответ 301 на HTTPS-URL при запросе по обычному HTTP также удовлетворяет проверку; принудительный HTTPS включён.

Если curl возвращает 526 (специфичный для Cloudflare код недействительного сертификата) или 502 (плохой шлюз), сертификат ещё не выдан. Pages автоматически предоставляет сертификаты Let's Encrypt, как только CNAME разрешается; отведите до 24 часов на первую выдачу. Для диагностики:

gh api /repos/ahmed-g-gad/apothem/pages \
  --jq '.https_certificate.state, .https_certificate.description'

state: approved означает, что выдача завершена. state: requesting означает, что выдача в процессе; ждите. Любое другое состояние требует перезапуска Pages (выключите и включите пользовательский домен через API).

2.6 Проверьте глубокие ссылки

curl -sSI https://apothem.ahmedgad.com/architecture/ | head -3

Ожидаемый вывод:

HTTP/2 200
server: GitHub.com
content-type: text/html; charset=utf-8

Ответ 404 по глубокой ссылке означает, что сборка статического сайта не подхватила страницу или развёртывание не завершилось. Запустите пересборку через gh workflow run publish-static-site.yml.

2.7 Запишите проверку

Добавьте строку в журнал статуса сайта оператора (или в журнал проверки этого руководства, если он ведётся встроенно) с датой, идентификацией оператора и выводом статуса Pages из gh api. Журнал проверки — это аудиторский след; каждое изменение конфигурации Pages оставляет строку.

3. Приложение для провайдера — Namecheap

Namecheap предоставляет DNS через вкладку «Advanced DNS» у регистратора. Оператор владеет ahmedgad.com здесь, когда NS-записи регистратора совпадают с dns1.registrar-servers.com и dns2.registrar-servers.com (значение Namecheap по умолчанию). Проверьте с помощью dig NS ahmedgad.com +short.

Шаги:

1. Войдите в Namecheap; откройте панель управления.
2. Нажмите Domain List в левой навигации; найдите ahmedgad.com; нажмите Manage.
3. Нажмите вкладку Advanced DNS.
4. Нажмите Add New Record. Выберите:
   • Type: CNAME Record
   • Host: apothem (без апекса, без завершающей точки)
   • Value: ahmed-g-gad.github.io. (с завершающей точкой)
   • TTL: Automatic (значение Namecheap по умолчанию; соблюдает 1800 секунд)
5. Нажмите зелёную галочку для сохранения.
6. Подождите от 5 до 10 минут распространения на границе Namecheap; затем вернитесь к независимому от провайдера ядру §2.4 для проверки dig.

Частый сбой: интерфейс Namecheap молча отклоняет CNAME-записи, когда запись A уже занимает тот же хост. Сначала удалите конфликтующую запись A; CNAME и A на одном хосте взаимно исключают друг друга согласно RFC 1034.

4. Приложение для провайдера — Cloudflare

Cloudflare DNS размещает апекс, когда NS-записи регистратора указывают на *.ns.cloudflare.com (значение Cloudflare по умолчанию после делегирования). Проверьте с помощью dig NS ahmedgad.com +short.

Шаги:

1. Войдите в Cloudflare; выберите зону ahmedgad.com.
2. Нажмите DNS -> Records в левой навигации.
3. Нажмите Add record. Выберите:
   • Type: CNAME
   • Name: apothem (Cloudflare автоматически добавляет апекс)
   • Target: ahmed-g-gad.github.io (без завершающей точки в интерфейсе Cloudflare)
   • TTL: Auto (значение Cloudflare по умолчанию; маршрутизируется через его границу)
   • Proxy status: DNS only (серое облако, не оранжевое)
4. Нажмите Save.

Выбор статуса прокси несёт смысловую нагрузку. Включение прокси Cloudflare (оранжевое облако) маршрутизирует трафик через границу Cloudflare до достижения GitHub Pages; это ломает выдачу Let's Encrypt в Pages, потому что Cloudflare предъявляет собственный сертификат. Держите прокси выключенным для начальной настройки; включите прокси позже, только решив, управлять ли сертификатом на границе Cloudflare.

5. Подождите от 1 до 2 минут распространения на границе Cloudflare; затем вернитесь к независимому от провайдера ядру §2.4.

Частый сбой: Cloudflare молча убирает завершающую точку из целей CNAME. Поле цели принимает ahmed-g-gad.github.io без завершающей точки; резолвер добавляет завершающую точку во время запроса. Не вводите завершающую точку в интерфейсе Cloudflare — это создаёт запись с двойной точкой, которая не разрешается.

5. Приложение для провайдера — Route53

Route53 размещает зону, когда NS-записи регистратора указывают на четыре сервера awsdns-*.com / awsdns-*.org / awsdns-*.co.uk / awsdns-*.net. Проверьте с помощью dig NS ahmedgad.com +short.

Шаги:

1. Откройте AWS Console; перейдите в Route53; нажмите Hosted zones; выберите зону ahmedgad.com.
2. Нажмите Create record.
3. Настройте:
   • Record name: apothem (Route53 автоматически добавляет апекс)
   • Record type: CNAME
   • Value: ahmed-g-gad.github.io (без завершающей точки)
   • TTL: 300 (5 минут; значения Route53 по умолчанию выше; понизьте TTL для более быстрого распространения во время перехода)
   • Routing policy: Simple routing
4. Нажмите Create records.
5. Подождите от 1 до 5 минут распространения Route53; вернитесь к §2.4.

Route53 поддерживает записи-алиасы, которые разрешаются во время запроса без CNAME-косвенности. Записи-алиасы здесь не используются, потому что цели алиасов ограничены ресурсами AWS (CloudFront, S3, ELB и т. д.), а ahmed-g-gad.github.io не является ресурсом AWS. CNAME верен.

Частый сбой: интерфейс Route53 принимает дублирующиеся имена записей с разными политиками маршрутизации; это проявляется как отказоустойчивая маршрутизация в стиле healthcheck, а не как простой CNAME. Убедитесь, что Routing policy показывает Simple routing перед сохранением.

6. Приложение для провайдера — Универсальный DNS

Для DNS-хостов, не охваченных именованными приложениями (DNS-панели по умолчанию большинства регистраторов — GoDaddy, Hover, Gandi, OVH, Porkbun, Domains.google, Network Solutions), примените независимую от провайдера форму CNAME:

Два класса сбоев, повторяющиеся в универсальных панелях:

• Несогласованность завершающей точки. Некоторые панели требуют завершающую точку; другие отклоняют её; немногие принимают любой вариант. Когда запись не распространяется через 30 минут, переключите завершающую точку и пересохраните.
• Конфликтующая запись A на том же хосте. CNAME и A на одном хосте нарушают RFC 1034 (Domain Names — Concepts and Facilities), раздел три о предпочтениях доменных имён. Удалите конфликтующую запись A перед добавлением CNAME.

После сохранения записи вернитесь к §2.4 для проверки dig.

7. Восстановление после сбоя

Процедура включения Pages имеет четыре задокументированных режима сбоя:

Если восстановление не удаётся после одного цикла соответствующей диагностики, эскалируйте к руководству по восстановлению выпуска (принудительный push свежей истории мог оставить конфигурацию Pages в несогласованном состоянии).

8. Перекрёстные ссылки

• Источник спецификации. Спецификация §2.5 перечисляет это руководство среди документационных результатов Кластера 4.
• Каноническое расположение CNAME. Файл CNAME расположен по пути site/public/CNAME и закоммичен в репозиторий; Pages читает его при каждой сборке.
• Поток восстановления. Руководство по восстановлению выпуска заново применяет конфигурацию Pages из снимка восстановления, когда последовательность перехода даёт сбой на полпути.
• Цикл выпуска. Каждый прогон выпуска включает задание сборки Pages, которое проверяет, что сайт отображается на пользовательском домене.