リポジトリへコミットし Web 公開できる GitHub Pages（ギットハブページ）についてまとめています。

GitHub リポジトリにファイルを入れ、そのまま Web サイトとして公開できます。

GitHub Pages now uses Actions by default | GitHub Blog

2022年8月より GitHub Pages は
GitHub Actions を用いてデプロイする方法がデフォルトになりました。
従来の Jekyll または静的ファイル（.html など）を用いた方法も使用できますが、
Jekyll・静的ファイルを公開する GitHub Actions もすでに存在しているため、
完全に GitHub Actions を用いた方法へ切り替える可能性もありそうです。

禁止される用途
GitHub Pages は、オンラインビジネス、eコマースサイト、主に商取引の円滑化またはサービスとしての商用ソフトウェアの提供 (SaaS) のどちらかを目的とする、その他のウェブサイトを運営するための無料のウェブホスティングサービスとしての使用を意図したものではなく、またそのような使用を許可するものでもありません。

通常 GitHub Pages は無料でソースを含めて公開されるので、
有料販売されるソフトウェアを GitHub Pages で公開してしまうと
支払いする事なく、ダウンロードできてしまう事になります。
有料向けはそれに適した Web サービスを使って下さい、という事でしょう。

これは法人での使用を禁止しているわけではありません。
法人用途でもフリーソフトのソースなどを公開する目的であれば
GitHub Pages を使っても構わない事になります。
またこの禁止用途は GitHub Pages なので、
GitHub そのものを禁止するものではありません。
例えば GitHub リポジトリで Web サイトのソース管理を行い、
そこから他のサービスでビルド・デプロイして公開する場合は
有料向けで使用しても良い事になります。

他にも禁止事項があります。

GitHub Pages の設定

リポジトリページの Setting をすると、
左サイドバーに Pages があります。

「Source」の選択により、動作が異なります。

GitHub Actions - GitHub Actions を用いて Web サイトのデプロイを行います。
Deploy from a branch - ブランチ内を静的サイトとして公開します。
または Jekyll を用いてビルドした静的サイトを公開します。（従来の方法）

それぞれ下記で紹介していきます。

GitHub Actions で公開する

Actions | GitHub (日本語)

GitHub に搭載された CI/CD です。
リポジトリの .github/workflows/ 内にワークフローの .yaml ファイルを作成し、
git push する事で、自動で処理を実施します。

「Source」で GitHub Actions を選択すると、ワークフローの選択ができます。
現在ワークフローはかなり多彩に公開されているため、
自身で作成する必要はなく、必要に応じて検索・選択するだけで使えるでしょう。

2022年8月に公開されたばかりなので、
.github.io への展開方法が新仕様に対応していないワークフローがあります。
（従来仕様の場合は Secret へトークンの入力が必要です）
数ヶ月中にも改善があるでしょう。

従来でも GitHub Actions を用いて GitHub Pages で公開する手段がありましたが、
公式手段を用いる事で、トークンの発行をせずにデプロイできるようになっています。

ページ運営者が 🎈 MkDocs を用いてビルド・デプロイする方法を
GitHub プロジェクトのサンプルとして公開しています。

🎈 fu-sen/GitHubPages-MkDocs | GitHub

静的サイトまたは Jekyll でビルドして公開する

GitHub リポジトリへの git push で使うのが通例ですが、
GitHub の Web 上でリポジトリを生成し、ファイルの作成・編集する事ができますので、
必ずしも Git の扱いに慣れている必要があるわけではありません。

HTML などを入れてそのまま公開できます。
また、🎈 Markdown を代わりに使用できます。.md ファイルを使用します。
ただし。GitHub のソース表示とは異なる解釈をするものがあります。
.md ファイル内で HTML の記載も可能です。.html ファイルの混在も可能です。

index.html はファイル名の省略で表示できますが、
Markdown は index.md を使用できます。
またこれらがない場合、プロジェクトページで表示される README.md が使われます。
ページの最小限は index.html・index.md・README.md のみとなります。

Not Found は 404.html および 404.md が表示されます。

ファイル.html は ファイル でも参照できます。
ファイル.md は ファイル.html または ファイル でも参照できます。
ファイル/ は物理的にディレクトリ（フォルダ）となり、参照できません。

独自ドメインを設定した場合は、ファイル CNAME が生成され、
その中にドメイン名が入ります。

_config.yml はテーマや title などのサイト全体の設定に使われます。
正しくは Jekyll の設定ファイルです。
Jekyll は当初から GitHub Pages に組み込まれている静的サイトジェネレータです。

設定

「Setting」に関係なく次の項目が存在します。

Custom domain
Enforce HTTPS

更に「Deploy from a branch」を選択する場合は次の項目もあります。

Source
Theme Chooser

以下に各項目を紹介しています。

Source 公開・非公開とブランチの選択

「Setting」で「Deploy from a branch」の場合に選択できます。
公開するブランチを選択します。公開・非公開のスイッチでもあります。

master branch - デフォルトの master ブランチ内をそのまま Web 公開します。
master branch /doc folder - doc/ フォルダ内を Web 公開します。
master ブランチでソースを公開している上で、
doc/ 内をドキュメント等の目的で Web 公開する事できます。
None - GitHub Pages を無効化します。

他のブランチが存在している場合、これらのブランチも一覧に表示されます。
GitHub Pages は当初 gh-pages ブランチを使用する方法が採用されていて、
現在は必須ではなくなっていますが、慣習的に使用しているリポジトリが存在します。

Theme Chooser テーマの適用・選択

「Setting」で「Deploy from a branch」の場合に選択できます。
シンプルに HTML・Markdown を制作した際、テーマを適用できます。

HTML で適用する場合、.html ファイル内は <body>～</body> 内の内容を入れ、
<head>～</head> の装飾は削除して下さい。
代わりに Front matter で latout: default を加えます。
テーマによって適用する layout を変更する必要があります。

---
layout: default
---

テーマによっていくつかのテーマを適用できます。
主に次のレイアウトで用意されていて、
ブログおよび Web サイトどちらでも使用できるようになっています。

layout: home - index.md などのトップページ。主にブログの一覧表示です。
layout: post - ブログ記事ページ。
layout: page - about.md など、記事以外の個別ページ。ブログではない Web サイト。

該当ページの GitHub プロジェクトページより
_layouts/ 内を参照して用意されているレイアウトを確認できます。

.md ファイルでテーマで使用できる項目があれば、
それを .html ファイルでも使用できます。

GitHub Pages 対応テーマ

簡単にテーマを適用できます。
この時テーマの選択とサンプルが表示されますが、
次のページからも参照可能です。

Supported themes | GitHub Pages

テーマを適用していない場合、Primer がデフォルトテーマとして適用されています。

pages-themes/primer | GitHun

適用すると _config.yml が生成されます。
_config.yml での設定内容は、ある程度テーマで共通しているところがあります。

lang: ja
title: Example Domain
description: example.net.eu.org
theme: jekyll-theme-slate
show_downloads: true
google_analytics: UA-TRACKING-ID
github:
  is_project_page: false
  zip_url: https://～/file.zip
  tar_url: https://～/file.tar.gz
  repository_url: https://github.com/～

themes: jekyll-theme-テーマ名 で統一されています。
title: サイト名。ヘッダに大きく表示します。
description: 説明。サイト名の下に表示します。
show_downloads: true にするとダウンロードリンクを表示します。
google_analytics: 設定している場合はトラッキング ID を入れます。
Google アナリティクス 4（GA4）の測定 ID は非対応の可能性があります。
github: 下層は空白を半角 2 文字以上入れて下さい。
- is_project_page: false にすると
  プロジェクトページへのリンクが非表示になる場合があります。
- zip_url: .zip ファイルのダウンロード URL を入れます。
- tar_url: .tar.gz ファイルのダウンロード URL を入れます。
- repository_url: 省略するとビルド元のプロジェクトになりますが、変更できます。

テーマによって追加の設定があります。
_layouts/default.html を参照してみて下さい。

pages-themes | GitHub

他に公開されているテーマ

Theme Chooser 以外でも Jekyll テーマで remote_theme に対応している場合、
_config.yml を生成し、remote_theme を入れるだけでテーマを適用できます。
Jekyll テーマ一覧へのリンクは Jekyll 公式サイトの次から参照できます。

Themes | Jekyll

指定する値は GitHub リポジトリで remote_theme: ユーザー/リポジトリ です。

例えば Just the Docs は次の GitHub リポジトリで公開されています。

pmarsceill/just-the-docs | GitHub

従って、 _config.yml に次を追加します。

remote_theme: pmarsceill/just-the-docs

これだけでテーマが適用されます。更にテーマに応じた設定の追加が可能です。
GitHub Pages ではわざわざリポジトリをクーロン・修正する必要はありません。
最小限でファイル管理を行えます。

Custom domain 独自ドメインの適用・設定

「Source」が「GitHub Actions」の場合、
GitHub Actions のワークフローによってはこの設定が無視されます。

独自ドメインを適用します。適用しない場合は次のアドレスになります。

https://ユーザー名.github.io/プロジェクト名 - 個人の場合
https://組織.github.io/プロジェクト名 - 組織の場合

※ ～.github.com/プロジェクト名 は古い記載で、現在は使用できません。

「Souce」で「Deploy from a branch」を選択している場合、
ファイル CNAME にドメイン名が入った状態で生成されます。
これは Settings で設定せずに CNAME ファイルを作って git push も可能です。
「Source」が「GitHub Actions」の場合は連動されなくなったため、
この項目で使用するドメイン名を設定する必要があります。

🎈 ネームサーバは次で設定します。

サブドメイン	種類	値
公開ドメイン名	CNAME	個人・組織.github.io

www などのサブドメインを付けない場合、
CNAME の代わりに ANAME・ALIAS レコードで設定できる場合があります。
これがネームサーバで対応していない場合、A レコードで設定が必要です。

Windows 以外では dig で検索できます。

dig fu-sen.github.io

Web でも検索可能です。Google が提供している dig があります。

Dig | G Admin Toolbox

「名前」に 個人・組織.github.io を入れて下さい。
レコードは A がデフォルトになっています。

ここでは fu-sen.github.io で実際に検索した結果です。

;; QUESTION SECTION:
;fu-sen.github.io.              IN      A

;; ANSWER SECTION:
fu-sen.github.io.       3600    IN      A       185.199.111.153
fu-sen.github.io.       3600    IN      A       185.199.109.153
fu-sen.github.io.       3600    IN      A       185.199.108.153
fu-sen.github.io.       3600    IN      A       185.199.110.153

現在は IPv6 も割り当てがあります。
レコード AAAA も参照して下さい。

;fu-sen.github.io.              IN      AAAA

;; ANSWER SECTION:
fu-sen.github.io.       3600    IN      AAAA    2606:50c0:8000::153
fu-sen.github.io.       3600    IN      AAAA    2606:50c0:8001::153
fu-sen.github.io.       3600    IN      AAAA    2606:50c0:8002::153
fu-sen.github.io.       3600    IN      AAAA    2606:50c0:8003::153

Windows では代わりに nslookup が使えます。Windows 10 でも使用可能です。

nslookup fu-sen.github.io

権限のない回答:
名前:    fu-sen.github.io
Addresses:  2606:50c0:8002::153
          2606:50c0:8001::153
          2606:50c0:8000::153
          2606:50c0:8003::153
          185.199.110.153
          185.199.109.153
          185.199.108.153
          185.199.111.153

この場合、ネームサーバは次の設定になります。

サブドメイン	種類	値
なし・@・ドメイン名	A	185.199.108.153
なし・@・ドメイン名	A	185.199.109.153
なし・@・ドメイン名	A	185.199.110.153
なし・@・ドメイン名	A	185.199.111.153
なし・@・ドメイン名	AAAA	2606:50c0:8000::153
なし・@・ドメイン名	AAAA	2606:50c0:8001::153
なし・@・ドメイン名	AAAA	2606:50c0:8002::153
なし・@・ドメイン名	AAAA	2606:50c0:8003::153

個人・組織によって IP アドレスが異なります。
必ず dig ・ nslookup で調べた上で設定して下さい。

www の有無

example.com が Custom domain として設定し使用する GitHub Pages の場合、
www.example.com も GitHub Pages のサーバに設定した場合、
www.example.com は example.com へ転送されます。

逆に www.example.com を Custom domain に入れていた場合は、
example.com は www.example.com へ転送されます。

独自ドメインへの転送

独自ドメインを設定した場合、そのその元になる ●●.github,io や
●●,github.io/プロジェクト で参照した場合は、
設定を行った独自ドメインへ転送されます。

GitHub Pages は設定を行った独自ドメインも
GitHub Pages で管理される事を期待しますが、
この独自ドメインを他の Web サービスで運用する事ができます。

例えば参照が多くなり、GitHub Pages の制限に達してしまっても、
従来使用していたアドレスは独自ドメインへの転送にして、
独自ドメインを他の Web サービスで運用する回避策を適用できます。
🎈 Cloudflare Pages や 🎈 Surge は転送量の制限がないので候補にできるでしょう。

Enforce HTTPS 常時 SSL の有効化

2016年6月15日以降に生成されたプロジェクトでは
個人・組織.github.io/プロジェクト名 が常時 https 固定になります。

独自ドメインを使用した場合は現在も選択できます。
従って独自ドメインであれば http での公開が現在でも可能です。

SSL 証明書には 🎈 Let’s Encrypt を発行し、有効な間は自動更新されます。
これに最低でも数分要するため、を入れて参照できるようになるまで数分要します。
発行にはネームサーバが反映されている必要があります。
ネームサーバにはキャッシュ（TTL）がある事にご注意下さい。

個人・組織.github.io で公開する

プロジェクトを後ろに付けない
個人.github.io または 組織.github.io でもページ公開できます。
個人・組織の自己紹介や Blog などの目的で使用できます。

ここでの「組織」は GitHub 上では Organization ・ Team の記載で、
法人用途以外でも設定して使用でき、組織内でプロジェクトを作成できます。
一人での作成も可能ですし、複数人での構成も可能です。
この機能があるため、現在個人で複数のアカウントを持つ事は非推奨になります。

プロジェクト名を 個人.github.io または 組織.github.io で作成するだけです。
その中に index.html などを含めます。

ここに入れた robots.txt は独自ドメインを使用しない
個人・組織.github.io/プロジェクト の Web ページにも影響があります。
また favicon などの画像もプロジェクトで meta タグ指定がない場合は反映されます。
Sitemap にも注意を要します。
この辺の問題を回避するために、プロジェクトに独自ドメインを割り当てたり、
サブドメインを使用できる 🎈 Cloudflare Pages ・ 🎈 Vercel で
Web サイトを公開するのが良いでしょう。

個人・組織ページに独自ドメインを割り当てる

個人ページ・組織ページにも Custom Domain を設定して、
独自ドメインを設定する事ができます。
●●.github.io に独自ドメインを設定する場合でも
プロジェクト名は ●●.github.io のままにして下さい

個人・組織ページに独自ドメインを設定すると、
個々のプロジェクトで独自ドメインを設定していない場合、
●●.github.io/プロジェクト は
独自ドメイン/プロジェクト での公開となります。

なお、個人・組織ページに独自ドメインを設定した場合は、
https の強制を無効にして、http での参照にする事ができます。
これはプロジェクト毎に設定可能です。

Node の gh-pages アプリでデプロイする

tschaub/gh-pages | GitHub

git コマンドを使う代わりに GitHub Pages を公開する目的で
リポジトリへコミットして公開する CLI が GitHub 内でいくつか存在します。
現在は GitHub Actions や 🎈 Vercel ・ 🎈 Cloudflare Pages を用いる前提で、
ビルド前のソースレベルをリポジトリへ入れておく事が多いですが、
ソースを公開せずに GitHub Pages を用いて公開したい場合に使えます。

単にコミットに必要な git コマンドを 1 コマンドで行っているので、
実際には GitHub Pages 用途以外でも使う事ができます。

Node.js をインストールしている状態で次を実行します。

npm i -g gh-pages

また予め GitHub のリポジトリを連携させておきます。

例えば 🎈 Hugo を使う場合は
public 内にビルドした index.html などが生成されるので、

hugo
gh-pages -d public

とすると gh-pages ブランチへコミットします。
あとは gh-pages ブランチを GitHub Pages として公開するよう設定します。

-a - git add ・ git remove のみを実行します。
-b ブランチ - コミットするブランチ。gh-pages 以外を指定できます。
-d フォルダ - コミットするフォルダ。./ で現在の場所です。※
-g タグ - タグを付与します。
-m メッセージ - コミットメッセージを続けます。デフォルトは Updates です。
-n - commit のみを行い、push しないようにします。
-o リモート - リモートを origin 以外にする場合に指定します。
-r リポジトリ - 他のリポジトリへコミットする場合は指定します。
-t - 頭に . が付くファイルを対象にします。

※ 運営者の経験で -d 省略時（-d "." 同等）でエラーが発生しています。

オプションが長くなる場合は pageage.json を含めます。

{
  "scripts": {
    "deploy": "gh-pages -d public/ -b master"
  }
}

あとは npm run deploy でデプロイできますが、
-- オプション でオプションを追加できるので、
これを用いてコミットメッセージを追加すると良いでしょう。

npm run deploy -- -m "\`readme.md\` を更新"

Q&A

_ ではじまるディレクトリ・ファイルが機能しません。

「Source」で「Deploy from a branch」を選択している場合、
静的サイトジェネータ Jekyll が動作します。
Jekyll は _ ではじまるディレクトリ・ファイルが特殊なファイルとして扱われるため、
_ ではじまるファイルが無視されてしまいます。

「Source」を「GitHub Actions」に変更して
「Static HTML」を適用する事で、
Jekyll を適用せずに静的ファイルを表示する事ができます。
静的サイトジェネータを使用している場合は、
GitHub Actions で存在しているかもしれないので、
GitHub プロジェクトの使用方法を変える良い機会でしょう。

またはプロジェクトのルートに空の .nojekyll を含めて下さい。
これにより Jekyll の動作が無効になります。

コミットする度にメール通知が届きます。

ネームサーバが設定したての場合や GitHub が推奨するレコード設定をしていない場合に
GitHub からメール通知が届きます。

Subject: [ユーザー/リポジトリ] Page build warning
The page build completed successfully, but returned the following warning for the master branch:
Your site’s DNS settings are using a custom subdomain, ドメイン名, that’s set up as an A record. We recommend you change this to a CNAME record pointing at ユーザー.github.io. For more information, see https://help.github.com/en/articles/using-a-custom-domain-with-github-pages.
For information on troubleshooting Jekyll see:
https://help.github.com/articles/troubleshooting-jekyll-builds
If you have any questions you can contact us by replying to this email.

🎈 EU.org を更なるサブドメインなしの状態で設定した場合、
CNAME・ALIAS・ANAME で設定しても実際には A レコードで設定されるため、
メール通知が届きます。
これを回避するのは他のサービスで Web 公開するようにします。
例えば 🎈 Vercel を使用できます。

プロジェクト名やユーザー名を変更した場合、URL は変化しますか？

独自ドメインを設定せずに ●●●.github.io/プロジェクト で使用している場合、
プロジェクト名の変更にともなって URL は変化します。
ただし今まで使われていた URL は新しい URL へ転送になり、Not Found にはなりません。

これは Custom Domain で独自ドメインを割り当てた場合、
従来が ●●●.github.io/プロジェクト の形式で使用していた場合も
●●●.github.io/プロジェクト は独自ドメインへの転送になります。

GitHub ユーザー名の変更を行った場合、
●●●.github.io が変化する事になりますが、
この場合も古い ●●●.github.io から転送されるようになります。

これらで Custom domain を設定していれば、URL は変化しないので、
あえてプロジェクト固有の Custom domain をサブドメインレベルでも良いので
割り当てておくのも手です。

GitHub Pages（github.io）

目次

公式サイト

使用制限・禁止用途