GitHub - Pages

提供: MochiuWiki : SUSE, EC, PCB

概要

GitHub Pagesは、GitHubリポジトリから直接Webサイトを公開できる静的サイトホスティングサービスである。
HTML、CSS、JavaScriptで構成された静的ファイルをリポジトリに配置するだけで、インターネット上に公開されたWebサイトを無料で運営できる。

GitHub Pagesで公開できるサイトは以下に示す2種類に分類される。

GitHub Pagesのサイト種別一覧
種別 説明
ユーザ・組織サイト <ユーザ名 または 組織名>.github.io という名前のリポジトリから公開するサイト
アカウントごとに1つのみ作成できる。
公開URLは https://<ユーザ名 または 組織名>.github.io となる。
プロジェクトサイト 既存のリポジトリから公開するサイト
1つのアカウントで複数作成できる。
公開URLは https://<オーナー名>.github.io/<リポジトリ名> となる。


GitHub Pagesは、プロジェクトのドキュメント、個人ポートフォリオ、ブログ、ランディングページ等の幅広い用途で利用されている。


GitHub Pagesの作成

ユーザ・組織サイト

ユーザサイトまたは組織サイトを作成するには、特定の命名規則に従ったリポジトリを作成する必要がある。

リポジトリ名は <ユーザ名>.github.io (個人アカウントの場合) または <組織名>.github.io (組織の場合) とする。
アカウントごとに作成できるユーザ・組織サイトは1つのみである。

リポジトリを作成後、デフォルトブランチ (通常は main) のルートディレクトリに index.html ファイルを配置することにより、サイトが公開される。

プロジェクトサイト

プロジェクトサイトは、既存のリポジトリに対してGitHub Pagesを有効化することで作成する。

プロジェクトサイトの公開URLは https://<オーナー名>.github.io/<リポジトリ名> となる。
<オーナー名> は、GitHubのユーザ名または組織名に対応する。

公開ソースの設定

GitHub Pagesの公開ソースは、リポジトリの[Settings] - [Pages]から設定する。

公開ソースには以下の2つの方式がある。

  • ブランチからの公開
    指定したブランチのルートディレクトリ (/) または /docs ディレクトリの内容を公開する。
    設定は [Settings] - [Pages] - [Branch]でブランチ名とディレクトリを選択して保存する。
  • GitHub Actionsでの公開
    カスタムワークフローを使用してビルド・デプロイを行う。
    actions/upload-pages-artifact でアーティファクトをアップロードして、actions/deploy-pages でデプロイする。
    ワークフローには pages: write および id-token: write の権限が必要である。


GitHub Actionsを使用したデプロイワークフローの基本構成を以下に示す。

 name: Deploy GitHub Pages
 
 on:
    push:
       branches: ["main"]
 
 permissions:
    contents: read
    pages: write
    id-token: write
 
 jobs:
    build:
       runs-on: ubuntu-latest
       steps:
          - uses: actions/checkout@v4
          - name: Build
            run: |
               # ビルドコマンドをここに記述する
          - 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:
          - id: deployment
            uses: actions/deploy-pages@v4



Jekyll

Jekyllとは

JekyllはRubyで実装された静的サイトジェネレータであり、GitHub Pagesに公式統合されている。
MarkdownファイルをHTMLに変換して、Liquidテンプレートエンジンを使用してレイアウトやコンポーネントを管理する。

ブランチからの公開を設定している場合、GitHub Pagesはリポジトリ内のファイルを自動的にJekyllでビルドする。

Jekyllを使用しない場合は、リポジトリのルートディレクトリに .nojekyll という空ファイルを配置することにより、Jekyllビルドを無効化できる。

_config.yml

_config.yml ファイルは、Jekyllサイトの主要な設定ファイルである。
リポジトリのルートディレクトリに配置する。

主要な設定項目を以下に示す。

 # サイトの基本情報
 title: サイトタイトル
 description: サイトの説明文
 url: "https://<username>.github.io"
 baseurl: ""   # プロジェクトサイトの場合は "/<repo>" を指定する
 
 # テーマの設定
 theme: minima
 
 # プラグインの設定
 plugins:
    - jekyll-feed
    - jekyll-sitemap
 
 # 除外ファイルの設定
 exclude:
    - Gemfile
    - Gemfile.lock
    - README.md
 
 # Markdownエンジンの設定
 markdown: kramdown


GitHub Pagesが自動的に上書きする設定項目があることに注意する。

GitHub Pagesが強制する設定
設定項目 強制される値 説明
lsi false 関連記事リストの生成を無効化する。
safe true ホワイトリスト外のプラグインを無効化する。
highlighter rouge シンタックスハイライトにRougeを使用する。


テーマ

JekyllテーマはサイトのデザインとレイアウトをまとめたRuby Gemパッケージである。

テーマの適用方法には以下の2つがある。

  • Web UIからの設定
    リポジトリの[Settings] - [Pages] - [Choose a theme]から選択する。
    選択すると _config.yml ファイル内に theme: が自動的に追加される。
  • _config.yml での設定
    GitHub Pagesがサポートするテーマは theme: テーマ名 で指定する。
    GitHubホスト外のテーマは remote_theme: owner/theme-repo で指定する。


テーマのカスタマイズはリポジトリ内に _layouts ディレクトリを作成し、テーマのレイアウトファイルを上書きすることで行う。

独自のCSSを追加する場合は、assets/css/style.scss に記述する。

コンテンツ作成

Jekyllのコンテンツはページとポストの2種類に分類される。

  • ページ
    独立したコンテンツ (About、Contact等) を作成する時に使用する。
    リポジトリのルート直下または任意のディレクトリに .md または .html ファイルとして配置する。
  • ポスト
    ブログ記事等の時系列コンテンツを作成する時に使用する。
    _posts/ ディレクトリに YYYY-MM-DD-タイトル.md という命名規則で配置する。


各コンテンツファイルの先頭には、YAMLフロントマターと呼ばれるYAML形式のメタデータブロックを記述する。

 ---
 layout: post
 title: "記事タイトル"
 date: 2026-03-24 12:00:00 +0900
 categories: [カテゴリ1, カテゴリ2]
 permalink: /custom-url/
 ---
 
 ここからMarkdownでコンテンツを記述する。


下表に、YAMLフロントマターで指定できる主要な項目を示す。

Front Matterの主要項目
項目 説明
layout 使用するレイアウトテンプレート名 (例: page, post, default)
title ページまたは記事のタイトル
date 公開日時 (ポストのみ)
categories カテゴリの配列
permalink カスタムURL


ローカルテスト

GitHub Pagesに公開する前に、ローカル環境でサイトを確認することを推奨する。

ローカルテストには、Ruby 2.7以上とBundlerおよびJekyllが必要である。
Ruby 3.0以上を使用している場合は、追加で webrick Gem のインストールが必要である。

ローカルテストの手順を以下に示す。

  1. リポジトリのルートディレクトリで依存Gemをインストールする。 
    bundle install

  2. Jekyll開発サーバを起動する。 
    bundle exec jekyll serve

  3. Ruby 3.0以上でwebrickエラーが発生した場合は、以下に示すコマンドを実行する。 
    bundle add webrick


Webブラウザから http://localhost:4000 にアクセスしてサイトを確認する。
ファイルを変更すると自動的に再ビルドされる。


カスタムドメイン

DNSレコードの設定

カスタムドメインをGitHub Pagesに設定するには、ドメインのDNS設定を変更する必要がある。

ドメインの種類によって設定するDNSレコードが異なる。

  • Apexドメイン (例: example.com) の場合
    ドメインのDNS設定に以下の4つのAレコードを追加する。


GitHub Pages用 AレコードのIPアドレス
タイプ 値
A 185.199.108.153
A 185.199.109.153
A 185.199.110.153
A 185.199.111.153


IPv6に対応する場合は、上記に加えてAAAAレコードも追加する。

  • サブドメイン (例: www.example.com) の場合
    ドメインのDNS設定にCNAMEレコードを追加し、<owner>.github.io を指定する。


リポジトリでのドメイン設定

DNSレコードの設定後、GitHubリポジトリ側でカスタムドメインを設定する。

設定手順を以下に示す。

  1. リポジトリの[Settings] - [Pages] - [Custom domain]フィールドにカスタムドメインを入力する。
  2. [Save]ボタンを押下して保存する。
  3. リポジトリのルートディレクトリに CNAME ファイルが自動的に作成され、カスタムドメインが記載される。


CNAME ファイルはファイル名を大文字で記述して、ファイル内にはドメイン名を1行で記載する。

HTTPS

GitHub Pagesではカスタムドメインに対してHTTPSを強制できる。

HTTPS証明書はLet's Encryptによって自動的に発行される。
証明書の発行には最大1時間掛かる場合がある。

HTTPS設定の手順を以下に示す。

  1. カスタムドメインのDNS設定とリポジトリのドメイン設定が完了していることを確認する。
  2. [Settings] - [Pages] - [Enforce HTTPS]のチェックボックスを有効にする。


Let's Encrypt証明書の自動更新を確実に行うため、ドメインのCAAレコードに letsencrypt.org を許可する設定を追加することを推奨する。

ドメイン検証

GitHub Pagesのドメイン検証機能を使用すると、他のGitHubユーザが自分のカスタムドメインをGitHub Pagesに設定することを防止できる。

ドメイン検証はGitHubアカウントの[Settings] - [Pages] - [Verified domains]から設定する。
検証はDNSのTXTレコードに指定の値を追加することで完了する。


静的サイトジェネレータ

Jekyll以外のジェネレータ

GitHub PagesはJekyll以外の静的サイトジェネレータにも対応している。
GitHub Actionsを使用してカスタムビルドワークフローを設定することにより、任意のジェネレータを使用できる。

下表に、主要な静的サイトジェネレータを示す。

主要な静的サイトジェネレータ
ジェネレータ 言語 特徴
Hugo Go 高速なビルド速度
大規模サイトに適している。
Next.js JavaScript (React) Reactベースのフレームワーク
SSG (静的サイト生成) モードで使用する。
Gatsby JavaScript (React) Reactベースの静的サイトジェネレータ
GraphQLによるデータ取得が特徴。
Nuxt JavaScript (Vue.js) Vue.jsベースのフレームワーク
SSG (静的サイト生成) モードで使用する。
MkDocs Python Markdownベースのドキュメントサイト生成に特化している。
Sphinx Python Pythonプロジェクトのドキュメント生成に広く使用されている。
Eleventy (11ty) JavaScript シンプルで柔軟な静的サイトジェネレータ


GitHub Actionsでのカスタムビルド

GitHub Actionsを使用したカスタムビルドワークフローの主要なアクションを以下に示す。

  • actions/upload-pages-artifact
    ビルド済みの静的ファイルをGitHub Pages用のアーティファクトとしてアップロードする。
    path パラメータで公開するディレクトリを指定する。
  • actions/deploy-pages
    アップロードされたアーティファクトをGitHub Pagesにデプロイする。
    デプロイされたページのURLが出力パラメータ page_url として返される。


Hugoを使用したデプロイワークフローの例を以下に示す。

 name: Deploy Hugo Site
 
 on:
    push:
       branches: ["main"]
 
 permissions:
    contents: read
    pages: write
    id-token: write
 
 jobs:
    build:
       runs-on: ubuntu-latest
       steps:
          - uses: actions/checkout@v4
            with:
               submodules: true
          - name: Setup Hugo
            uses: peaceiris/actions-hugo@v3
            with:
               hugo-version: "latest"
          - name: Build
            run: hugo --minify
          - uses: actions/upload-pages-artifact@v3
            with:
               path: ./public
 
    deploy:
       needs: build
       runs-on: ubuntu-latest
       environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
       steps:
          - id: deployment
            uses: actions/deploy-pages@v4



制限事項

技術的な制限

GitHub Pagesを使用する時は、以下に示す技術的な制限に注意が必要である。

GitHub Pagesの技術的な制限
項目 制限値 備考
リポジトリサイズ 1[GB]推奨 ソースリポジトリのサイズ上限の目安
公開サイトのサイズ 1[GB]以下 デプロイされるサイトの合計サイズ
帯域幅 100[GB] / 月 月間のデータ転送量上限
ビルド時間 10分 Jekyll または カスタムビルドの実行時間上限
アーティファクトサイズ 10[GB] GitHub Actionsアーティファクトのサイズ上限


禁止されている用途

GitHub Pagesは静的サイトホスティングサービスであり、以下に示す用途での使用は禁止されている。

  • オンラインビジネス、eコマースサイト、商業目的のトランザクション処理を主目的とするサイト
  • サーバサイドの処理が必要なWebアプリケーション (データベース接続、サーバサイドスクリプトの実行等)
  • パスワードのクラッキング、ネットワーク攻撃等の不正行為に使用するサイト
  • GitHubのサービス利用規約に違反するコンテンツの公開


GitHub PagesはGitHubの利用規約に従って運営されており、上記の禁止事項に違反した場合はサービスが停止される場合がある。


トラブルシューティング

Jekyllビルドエラー

Jekyllビルドで発生しやすいエラーとその対処法を以下に示す。

  • _config.yml 構文エラー
    YAMLファイルにタブ文字を使用している場合はスペースに置き換える。
    ファイルの文字エンコーディングがUTF-8であることを確認する。
    コロン (:) の後には必ずスペースを入れる。
    文字列にコロンが含まれる場合は引用符で囲む。
  • 非対応プラグインエラー
    GitHub Pagesはセキュリティ上の理由から使用できるJekyllプラグインを制限している。
    使用できるプラグインは公式ドキュメントで確認する。
    非対応プラグインを使用する場合は、GitHub Actionsでのカスタムビルドに切り替える。
  • Ruby 3.0以上での webrick エラー
    bundle add webrick を実行して、webrick Gemを追加する。


カスタムドメインの問題

カスタムドメイン設定で発生しやすい問題とその対処法を以下に示す。

  • DNS設定が反映されない。
    DNS設定の変更が反映されるまで最大24時間かかる場合がある。
    dig コマンド や whatsmydns.net 等のツールでDNS伝播状況を確認する。
  • CNAME ファイルの形式エラー
    ファイル名は大文字の CNAME とする。
    ファイル内にはカスタムドメインを1行のみ記載する。
    余分な空行や文字が含まれていないことを確認する。
  • HTTPS設定が有効にならない
    Enforce HTTPSは、DNS設定が正しく完了してから有効にする。
    証明書の発行には最大1時間掛かる場合がある。
    DNS設定後に1度カスタムドメインを削除して再設定すると解決することがある。



「https://mochiu.net/index.php?title=GitHub_-_Pages&oldid=14579」から取得