GitHubリポジトリにはスポンサーボタンを表示する機能がありますが、これをまとめて設定ツールを書きました。

GitHub Sponsorship button

GitHubリポジトリに、スポンサーボタンを表示するには次のような条件が必要です。(2019-10-27現在)

  1. GitHubリポジトリのSettingsで"Sponsorship"の✔をいれて有効化する
  2. リポジトリの.github/FUNDING.ymlにGitHub SponsorsやPatreonなどのfunding platformsの情報を入れる

具体的な手順は次のドキュメントに書かれています。

つまり、それぞれのリポジトリに.github/FUNDING.ymlをコミットする必要があります。 これだと更新が面倒そうなので、一括で複数のリポジトリの.github/FUNDING.ymlのGitHub Sponsorsを更新するツールを書きました。

Note: Organizationの場合は、ツールを使わなくても.githubリポジトリを使うことで一括設定が可能なので、その方法は後述します。

github-funding-yml-updater

github-funding-yml-updaterは複数のリポジトリの.github/FUNDING.ymlをGitHub API経由で更新するツールです。 GitHub APIでリポジトリを更新するので、それぞれのリポジトリを手元にcloneする必要はありません。

使い方

リポジトリの準備

まず、更新するリポジトリの定義などの準備をします。

次のような形式で更新したいリポジトリを改行区切りにしたlist.txtなどのテキストファイルを用意します。

owner/repo
owner/repo@branch
https://github.com/owner/repo

たとえば、curljqを使って、GitHubの検索APIで自分のリポジトリ一覧を取得してlist.txtを作れます。

export GH_USER="azu"
curl -s "https://api.github.com/search/repositories?q=user:${GH_USER}&&per_page=100" | jq ".items[].full_name" > list.txt

# ....
$ cat list.txt
"azu/promises-book"
"azu/awesome-commit-english"
"azu/NSDate-Escort"
"azu/large-scale-javascript"
"azu/JavaScript-Plugin-Architecture"
"azu/github-reader"
"azu/browser-javascript-resource"
"azu/multi-stage-sourcemap"
"azu/irodr"
"azu/parcel-typescript-example"
...

次に、GitHubのアクセストークンを用意します。 Scopeはrepoがあればいいので、次のURLから必要に応じてpersonal access tokenを作成してコピーしておきます。

リポジトリを更新する

github-funding-yml-updaterはNode.jsで書かれたツールなのでnpmでコマンドラインツールとしてインストールします。

npm install github-funding-yml-updater -g

慣れてる人はnpxコマンドでも利用できます。(複数のコマンドが入ってるので-p指定が必要)

npx -p github-funding-yml-updater github-funding-yml-updater [options]

github-funding-yml-updaterコマンドがインストールされるので、次のように実行できます。 先ほど用意したlist.txt--list-fileに指定して、.github/FUNDING.ymlのGitHub Sponsorにazuを追加する例です。

デフォルトはDryRunモードなので、実際にリポジトリは更新せずに、更新するかどうかだけを表示します。

## --writeがない場合はDryRunで実行する
$ github-funding-yml-updater --mode add --user azu --list-file list.txt --token あなたのGITHUB_TOKEN

Mode: DryRun mode
User: azu
azu/promises-book: No Update
azu/awesome-commit-english: Try to Update
azu/NSDate-Escort: Try to Update
azu/large-scale-javascript: Try to Update
azu/JavaScript-Plugin-Architecture: Try to Update
azu/github-reader: Try to Update
...

実際にリポジトリの.github/FUNDING.ymlを更新したい場合は、--writeフラグを追加します。

## --writeで実際に書き込む
$ github-funding-yml-updater --mode add --user azu --list-file list.txt --token あなたのGITHUB_TOKEN --write

Mode: Write mode
User: azu
azu/promises-book: No Update
azu/awesome-commit-english: Try to Update
azu/NSDate-Escort: Try to Update
azu/large-scale-javascript: Try to Update
azu/JavaScript-Plugin-Architecture: Try to Update
azu/github-reader: Try to Update
...

これでlist.txtにあるリポジトリの.github/FUNDING.ymlをまとめて更新できます。

その他の--modeとしてユーザーを削除するdeleteや既存のFUNDING.ymlを指定して上書きするoverwriteなどがあります。 詳しいコマンドの使い方はREADMEや--helpで見てください。

GitHubリポジトリのSettingsで"Sponsorship"の✔をいれて有効化する

最初に書いたように.github/FUNDING.ymlを置いただけだと、GitHubのスポンサーボタンは表示されません。

ユーザーの場合は、各リポジトリSettingsで"Sponsorship"の✔をいれて有効化する必要があります。

Sponsorships

この"Sponsorship"の✔は現在APIがないため手動で更新が必要です。

github-funding-yml-updaterには、この設定を補助するツールもはいっています。

github-funding-yml-updaterをインストールするとgithub-funding-yml-settingsという別のコマンドもインストールされています。 github-funding-yml-settings--list-fileを渡す設定するためのURLを出力してくれます。

npm install github-funding-yml-updater -g
github-funding-yml-settings --list-file list.txt

# リポジトリごとの設定URLを出力する
https://github.com/azu/example1/settings#repository-funding-links-feature
https://github.com/azu/example2/settings#repository-funding-links-feature

あとはこの設定ページから1コづつ"Sponsorship"の✔をいれていくだけです。

Organizationの一括設定

GitHub Organizationの場合は.githubという名前のリポジトリを使うことで、Organization全体に一括設定が可能です。

たとえば、efcl/.githubというリポジトリにFUNDING.ymlなどをのGitHubメタファイルを配置すると、 そのOrganizationにあるリポジトリに反映されます。

注意点として、.githubリポジトリのSettingsで"Sponsorship"の✔を入れないとスポンサーボタンは有効化されません。

この機能はCreating a default community health file for your organization - GitHub Helpにも書かれているようにCONTRIBUTING.mdCODE_OF_CONDUCT.mdSECURITY.mdなどのファイルも配置できます。

その他: github:buttons

github:buttonsはGitHub Sponsorのボタンに対応しています。

次のような感じで、ウェブサイトにGitHubと似たようなスポンサーボタンを配置できます。

Sponsor

おわりに

github-funding-yml-updaterを使ったリポジトリの.github/FUNDING.ymlの一括アップデートについて書きました。

Organizationについては、.githubリポジトリを使うことで一括で設定できます。

ユーザー単位のリポジトリについては現状では一括設定する.githubリポジトリはありません。 ユーザースコープのメタリポジトリについては、次のIssueで話し合われています。