The Power の紹介

2024-04-20

Kensuke Nagae @kyanny

Kanazawa.rb meetup #140

The Power とは

• GitHub API を呼び出すシェルスクリプトのコレクション
• ↑を書きやすくするためのフレームワーク
• その他いろいろなツール・スクリプトがごちゃ混ぜになっているプロジェクト
• GitHub のサポートエンジニア David Morris (@gm3dmo) さんが数年かけてコツコツ書き溜めたスクリプト集のリポジトリを GPLv3 ライセンスで公開している
• 検証用 GitHub Enterprise Server へのテストデータ投入を楽にするために作られた

https://github.com/gm3dmo/the-power

The Power の特徴

• とにかくスクリプトの数が多い
• 500 を優に超える
• 初期設定を終えれば即、実行可能なスクリプト
• GitHub API のドキュメントからコピペするよりはやい
• 手元で自由に書き換えて使うと良い
• テストデータをサッと作りたいときに便利
• 大量のテストデータや込み入ったテストデータを作るシナリオのスクリプトもある
• GitHub App のセットアップを簡単にできる（後述）

The Power の歩き方

• docs/ にあるドキュメントを読む
• https://github.com/gm3dmo/the-power/tree/main/docs
• リポジトリのトップページは長すぎるため
• セットアップ手順を読む
• 最新のリリースをダウンロードするもよし、git clone するもよし
• 具体的な手順は後述
• スクリプト名や API エンドポイントの URL などで使うべきスクリプトを探す
• grep FOOBAR *.sh

セットアップ手順 A

• python3 configure.py
• smee.io が開くのでびっくりする
• 実行後に .gh-api-examples.conf を編集して organization や user を変更する必要あり

セットアップ手順 B

• configure.py をオプション付きで実行する
• オプション一覧は --help 参照
• smee.io が開くが二度目なのでびっくりしない
• 実行後に .gh-api-examples.conf を編集しなくて良い

セットアップ手順 C

• 手順 A のようにオプション付きで実行するスクリプトがある
• cp the-power-dotcom.skeleton ~/.the-power-dotcom.conf
• vim ~/.the-power-dotcom.conf
• ./dotcom-configure.sh
• しかしエラーが出て動かない
• よくある
• このあたりから advanced な領域になってくる

セットアップ手順 D

• $ ./zdpower kzrb-meetup-140
• 引数で指定した名前のディレクトリを作り The Power を git clone し dotcom-configure.sh を実行する
• zdpower を PATH の通ったディレクトリに配置するとコマンド一発で任意の場所に The Power スクリプト一式をセットアップできる
• 問い合わせ番号ごとに異なる検証環境を作ってテストデータを投入する、そのために個別にセットアップした The Power プロジェクトを作るために作られた
• zd = Zendesk

The Power と GitHub App (1)

• そもそも GitHub App とは何か
• めっちゃ雑にいうと App というよりサービスアカウント
• ユーザーアカウントではなくアプリとしてコミットしたりコメントしたりできる
• GitHub App を設定画面から登録→ユーザー or organization アカウントにインストール→API を呼び出してアプリのインストールアクセストークンを生成し個人アクセストークンの代わりに使って他の API を呼び出す
• 一連のセットアップ過程が長い・難しい・面倒

The Power と GitHub App (2)

• The Power の tiny-* スクリプトシリーズを使うと GitHub App を使い始めるまでの煩雑さを軽減できる
• The Power 自体のセットアップがすでに煩雑ではある
• Using a GitHub App with The Power
• 英語かつ文字ばかりだが GitHub App の登録から順を追って手順を説明している

tiny-* シリーズの紹介

• tiny-call-get-installation-token.sh
• インストールアクセストークンを発行して表示する
• tiny-dump-app-token.sh
• やってることは↑とほぼ同じ、表示がシンプル
• tiny-call-get-jwt.sh
• インストールアクセストークン発行 API を呼び出すために必要な JWT（認証情報）を生成する
• ↑のスクリプトの内部で使われている
• tiny-create-* 他
• インストールアクセストークンを使って書き込み系の API を呼び出す

おすすめの使い方

• API を呼び出す別のスクリプトの中から tiny-call-get-installation-token.sh を使う
• GITHUB_TOKEN=$(./tiny-call-get-installation-token.sh | jq -r '.token') みたいな感じで
• tiny-create-commit-timeserial-file.sh や tiny-create-check-run.sh を雛形にするのも良い

デモ