esaの記事更新によって GitHubの任意のリポジトリに記事のMarkdownファイルをpushできる機能です。

この機能とGitHub Actions や静的サイトジェネレーターを組み合わせることで、特定のカテゴリ配下の記事のみを外部ブログとして公開したりすることも可能になります。

# 設定方法

## 1. push先のGitHub リポジトリの用意

push先のリポジトリがまだ存在しない場合、 https://github.com/new で新しくリポジトリを作成します。

リポジトリはpublicでもprivateでも構いませんが、**"Add a README file"** のチェックを入れるなどして必ず初期化しておいてください。

> [!WARNING]
> リポジトリを初期化していない場合、Webhookが正常に作動しません。

## 2. GitHub の Access Tokenを作成

[New Fine-grained Personal Access Token](https://github.com/settings/personal-access-tokens/new) のページで新しくpersonal access tokenを生成します。

動作に必要な最低限の権限は以下になります。

- Repository access: **Only select repositories**
    - 1.で用意したリポジトリを指定
- Contents: **Read and Write**
    - このとき、自動的に Metadata: **Read-only** も選択されます


> [!NOTE]
> Personal Access Token (Classic) にも対応しています

## 3. esa上でGitHub Webhookを作成

チームのownerがSettings > "Webhook・外部ツールへ通知" のページからGitHub Webhookの設定を行います。

<img width="871" alt="ss 2024-09-05 14.50.20.png (111.6 kB)" src="https://img.esa.io/uploads/production/attachments/105/2024/09/05/1/4acf1ac9-5a7b-4532-9399-a9b7d79cfe1a.png">

- esa Root Category
    - ここで設定したカテゴリの配下で記事がShipitで作成・更新されたときにGitHubへ記事のMarkdownファイルをpushします
- Repo
    - 1\. で用意したリポジトリを `user/repo` の形式で入力します
- Branch
    - push先のブランチです
    - 入力されたブランチが存在しない場合は、 `main` もしくは `master` ブランチを元に自動的にブランチを作成します
- Output Directory
    - Markdownファイルが出力されるディレクトリです
- API Access Token
    - 2\. で用意したAccess Tokenを入力します


> [!WARNING]
> esa Root Categoryには正規表現を使用することができません

# トラブルシューティング

## GitHub Webhookが発動しない

記事を作成・保存してもGitHub Webhookが発動しない場合は以下のような原因が考えられます。

1. github webhookで指定した "esa Root Category" が記事のカテゴリと前方一致していない場合
2. shipitでなくwipで記事を保存していた場合

## GitHub Webhookがエラーになる

記事を作成・保存したときにGitHub Webhookでエラーが発生する原因として以下のような場合が考えられます。

1. push先のGitHubリポジトリが初期化されていない場合
2. GitHub Access Tokenの権限が足りていなかった場合
3. github webhookで指定したbranchがgithub上にない場合
    - mainかmasterブランチがあれば自動的に作成しますが、それらも存在しない場合はエラーになります

なお、GitHub Webhook作動中にエラーが発生した場合は下記の ⚠ アイコン上でエラーメッセージを確認できます。

<img width="1117" alt="ss 2024-08-20 15.50.13.png (165.0 kB)" src="https://img.esa.io/uploads/production/attachments/105/2024/09/05/1/12a214ab-ebf5-449a-8ecb-9a8d5d7ab3dd.png">