Improve this page

GitHub Actions

JekyllサイトをGitHub Pagesで構築する時、標準的なフローは、セキュリティ上の理由と、サイトのセットアップをより簡単にするために制限されています。ビルドをより詳細に制御し、GitHub Pagesでサイトをホストするために、GitHub Actionsを使用できます。

Actionsを使用する利点

gemsetの制御

  • Jekyll version — 現在有効な3.8.5にかわり、好きなバージョンのJekyllを使用できます。たとえば、4.0.0やリポジトリを直接ポイントします。
  • Plugins — サポートされているバージョンリストにあるかどうかに関係なく、Jekyllプラグインを使用できます。サイトの_pluginsディレクトリに配置された*.rbファイルも使用できます。
  • Themes — Actionsなしでカスタムテーマを使用することは可能ですが、より簡単になります。

ワークフローの管理

  • Customization — Actionsを実行するワークフローファイルを作成することにより、カスタムビルドステップを指定したり、環境変数を使用したりできます。
  • Logging — ビルドログは表示され、詳細に調整できるため、Actionsを使用してエラーをデバッグするのがよりに簡単になります。

ワークスペースのセットアップ

何よりもまず必要なのは、GitHubでホストされているJekyllプロジェクトです。既存のJekyllプロジェクトを選択するか、リポジトリがまだホストされていない場合はクイックスタートに従ってGitHubにプッシュします。

このページでは、masterブランチからのビルドのみを取り上げます。ですので、masterブランチで作業していることを確認してください。必要に応じて、デフォルトのブランチに基づいて作成できます。 Actionがサイトを構築すると、書き出しディレクトリのコンテンツが自動的にgh-pagesブランチにプッシュされ、配信に使用できるようになります。

ここで使用するActionは、デプロイが成功するたびにgh-pagesブランチを作成(または既存のものをリセット)します。
したがって、本番環境ビルドのデプロイに使用される既存のgh-pagesブランチがある場合は、コンテンツのバックアップを別のブランチに作成して、必要に応じて簡単にロールバックできるようにしてください。

このページの残りの部分で使用するJekyllサイトは、最初は_config.yml、index.mdページ、およびGemfileのみで構成されています。 内容はそれぞれ次のとおりです。

# _config.yml

title: "Jekyll Actions Demo"

---
---

Welcome to My Home Page

{% assign date = '2020-04-13T10:20:00Z' %}

- Original date - {{ date }}
- With timeago filter - {{ date | timeago }}

# Gemfile

source 'https://rubygems.org'

gem 'jekyll', '~> 4.0'

group :jekyll_plugins do
  gem 'jekyll-timeago', '~> 0.13.1'
end

デモサイトでは、Jekyll 4とサードパーティプラグインを使用しています。どちらも現在はGitHub Pagesでの使用はホワイトリストに登録されていません。プラグインを使用すると、日付が今日からどれだけ遡っているかを示します。例えば 日付を2016-03-23T10:20:00Zと指定し、現在の日付が2020-04-13T10:20:00Zである場合、出力は4 years and 3 weeks agoになります。

私たちが使用しているアクションは、Ruby gemと依存関係のインストールを処理します。これによりユーザーの設定がシンプルになりますが、古いバージョンのBundlerで生成された Gemfile.lockもチェックインすると問題が発生する可能性があります。

Actionのセットアップ

GitHub Actionsは、ディレクトリパス.github/workflows（先頭のドットに注意してください）内のYAMLファイルを使用してリポジトリに登録されます。 ここでは、簡単にするためにマーケットプレイスのJekyll Actionsを使用します。

GitHubインターフェースを使用するか、YAMLファイルをワークフローディレクトリパスに手動でプッシュすることで、ワークフローファイル、たとえばgithub-pages.ymlを作成します。 基本の内容は次のとおりです。

name: Build and deploy Jekyll site to GitHub Pages

on:
  push:
    branches:
      - master

jobs:
  github-pages:
    runs-on: ubuntu-16.04
    steps:
      - uses: actions/checkout@v2
      - uses: helaili/jekyll-action@2.0.1
        env:
          JEKYLL_PAT: ${{ secrets.JEKYLL_PAT }}

上記のワークフローは次のように説明できます：

  • masterブランチのみに対してon.push条件を使用してビルドをトリガーします—これにより、アクションが他のブランチのプッシュでgh-pagesブランチを上書きするのを防ぎます。
  • ジョブのnameがYAMLファイル名と一致します： github-pages
  • checkout actionは、リポジトリのクローンを作成します。
  • helaili/jekyll-action@2.0.0を使用して、選択したactionとversion numberを指定します。これはビルドとデプロイを処理します。
  • 使用するアクションの秘密のenvironment variableへの参照を設定します。JEKYLL_PATは個人アクセストークンであり、次のセクションで詳しく説明します。

on.push条件を使用する代わりに、on.scheduleパラメーターを使用してscheduleでビルドをトリガーできます。たとえば、ここではcrontab guruサイトでテストできるcron構文を指定して、毎日午前0時にビルドします。

on:
  schedule:
    - cron:  '0 0 * * *'

アスタリスクが誤って評価されるのを防ぐために、この文字列は引用符で囲む必要があることに注意してください。

権限を与える

actionには、gh-pagesブランチにプッシュする権限が必要です。そのため、GitHubプロファイルでGitHub authentication tokenを作成し、_Secrets_を使用してビルドで環境変数として設定する必要があります。

  1. GitHubプロファイルのDeveloper Settingsで、Personal Access Tokensセクションに移動します。
  2. トークンをCreateします。”GitHub Actions”のような名前を付け、public_repos（またはプライベートリポジトリのrepo scope全体）への権限があることを確認します—アクションがgh-pagesブランチにコミットするために必要です。
  3. トークンの値をコピーします。
  4. リポジトリの Settings へ行き、Secrets タブへ進みます。
  5. JEKYLL_PAT (重要)というトークンをCreateします。それに先ほどコピーした値を与えます。

ビルドとデプロイ

master上のローカル変更をプッシュすると、actionがトリガーされビルドを開始します。

進行状況を確認してビルドエラーを確認するには、次のいずれかの方法でビルドのstatusを確認します。

  • commitを見る
    • GitHubのリポジトリレベルビューに移動します。最新のコミット（上部近く）の下で、コミットメッセージの横にチェックまたは_X_としてステータスシンボルが表示されます。カーソルを合わせて、detailsリンクをクリックします。
  • Actionsタブ
    • リポジトリのActions他部へ移動します。jekyllワークフロータブをクリックします。

すべてがうまくいけば、全ステップが緑色になり、ビルドされたアセットがgh-pagesブランチに存在するようになります。

ビルドが成功すると、GitHub Pagesはリポジトリのgh-pagesブランチに保存されているサイトを公開します。actionがこれを処理するので、gh-pagesブランチをセットアップしたり、GitHub Pagesを有効にする必要はありません。 （プライベートリポジトリの場合、有料プランにアップグレードする必要があります）

live siteを表示するには：

  1. リポジトリのenvironmentタブへ移動します。
  2. デプロイされたサイトのURLを見るためにView Deploymentをクリックします。
  3. そのURLでサイトを見ます。timeagoフィルターが期待どおりに機能していることを確認します。
  4. 必要に応じて、このURLをリポジトリのメインページとREADME.mdに追加して、人々が簡単に見つけられるようにします。

サイトをさらに変更する必要がある場合は、masterにコミットしてプッシュします。 ワークフローにより、サイトが再度ビルドとデプロイされます。

gh-pagesブランチを直接編集しないでください。変更はActionからの次の正常なデプロイで失われます。

外部リンク

  • jekyll-actionsはGitHub Marketplaceで利用可能なactionであり、このガイドで使用していました。
  • jekyll-actions-quickstartは、jekyll-actions actionのライブデモを含む非公式リポジトリです。そのプロジェクトは、新しいサイトを作成するためのテンプレートとして使用できます。