Local development で見落とされがちな risk のひとつは、GitHub token の lifetime です。gh、script、private repository の clone、local automation を楽に動かすために、machine 上に long-lived PAT を置いたり、GitHub CLI の OAuth token に頼ったりすることは珍しくありません。便利ですが、log、shell history、dotfiles、backup、browser extension などから漏れたときの影響範囲は小さくありません。

今日紹介する suzuki-shunsuke/ghtkn は、この問題に向けた small tool です。Go 製 CLI で、GitHub App の Device Flow を使って 8 時間有効な User Access Token を生成し、その token を local backend に保存します。Default backend は OS keyring です。Container や microVM のように keyring が使いにくい環境では、text backend や agent backend に切り替えられます。

公開時点の GitHub page では、約 178 stars、1 fork。主な言語は Go、license は MIT です。Release page では v0.2.4 が latest stable release として表示され、v0.2.5 系の pre-release も見えます。Repository の current USAGE.md に生成されている help text は version 0.2.5 を示しています。

プロジェクト概要

項目内容
Repositorysuzuki-shunsuke/ghtkn
位置づけGitHub App User Access Token で local GitHub authentication を行う CLI
Stars約 178
Forks1
主な言語Go
LicenseMIT
Latest stable releasev0.2.4

解くのは local long-lived token の習慣

ghtkn は新しい GitHub client を作る tool ではありません。「local command が GitHub token をどう取得するか」を、より short-lived で control しやすい形にする tool です。

使うのは traditional PAT ではなく、GitHub App User Access Token です。User はまず Device Flow を有効にした GitHub App を作り、Client ID を ghtkn.yaml に書きます。そのうえで次の command を実行します。

ghtkn get

初回は GitHub device login page で authorization します。完了すると、ghtkn は ghu_ で始まる user access token を出力します。README によると、この token の validity は 8 時間です。次回以降は cached token がまだ有効なら再利用し、期限切れなら再度 authorization flow に進みます。

この model の大事な点は、Client ID が secret ではないことです。Local machine に GitHub App private key や client secret を保存する必要がありません。また token の permissions は、GitHub App 側の権限と user 自身の権限の両方で制限されます。App にない権限は増えず、user がアクセスできない repository にもアクセスできません。

gh と Git credential helper を wrap できる

README で示されている直感的な使い方は、ghtkn get を GitHub CLI に渡す形です。

env GH_TOKEN=$(ghtkn get) gh issue create -R owner/repo --title "Hello" --body "Created by ghtkn"

実運用では shell wrapper を用意し、GH_TOKEN / GITHUB_TOKEN が未設定のときだけ ghtkn get を呼ぶ形にできます。日常 command は gh pr view、gh issue create、gh api のままです。変わるのは token source で、long-lived token ではなく short-lived GitHub App user token になります。

もうひとつ重要なのが Git Credential Helper です。ghtkn >= v0.1.2 では次のように Git の HTTPS credential flow に接続できます。

git config --global credential.helper '!ghtkn git-credential'

Documentation では、既存の helper がある場合に空の helper = で helper list を reset する必要がある点も説明されています。これをしないと、Git が macOS keychain など古い helper を優先して呼び続けることがあります。

この detail は実務的です。Token leak は tool 本体ではなく、「新しい設定を使っているつもりだったが、実際には古い credential helper が使われていた」という運用のズレから起きることがあります。ghtkn が troubleshooting を docs に含めているのは、team adoption では大事です。

複数 GitHub App を directory ごとに切り替える

ghtkn.yaml には複数の app を設定できます。Command argument や GHTKN_APP でどの app を使うかを選べます。README では direnv を使い、repository directory ごとに app を切り替える例が紹介されています。.envrc に書くのは token ではなく app name です。

これは permission boundary を分けたい user に向いています。Personal repository では low-permission app、company organization では特定 repository にだけ installed された app、open source maintenance では別 app、という形にできます。User から見れば command は ghtkn get、または wrapper された gh のままです。一方で security boundary は app installation と permissions で分けられます。

Default low-permission policy にも合います。README では、追加 permissions のない app でも public repository の read に使え、unauthenticated API rate limit を避けるのに役立つと説明されています。Issue、PR、contents、statuses などの write が必要になったときだけ、該当 app に permission を追加し、target repository に install します。

Backend は desktop、container、microVM をカバーする

Default では、ghtkn は token を OS keyring に保存します。Windows Credential Manager、macOS Keychain、GNOME Keyring です。通常の desktop development ではこれが自然な選択です。

ただし最近の local workflow は container、devcontainer、microVM、remote shell の中で動くことも多く、そこでは keyring が使えない場合があります。ghtkn はそのために GHTKN_BACKEND を提供しています。

  1. keyring: default backend。System keyring を使う。
  2. text: permission 0600 の plaintext file に token を保存する。
  3. agent: local agent が AES-256-GCM で token cache を暗号化する。

text backend は簡単ですが、docs では directory を git や cloud sync に入れないこと、disk encryption を有効にすることが推奨されています。agent backend は OS keyring がない環境でも encrypted cache を使いたい場合に向いています。ただし agent の起動、passphrase unlock、socket / key / token directory の管理が必要です。

この設計により、ghtkn は単なる desktop PAT replacement ではなくなっています。Devcontainer で CLI agent を動かす場合や、microVM で isolated development をする場合でも、GitHub token を long-lived environment variable として晒し続ける必要を減らせます。

Agent workflow と相性がよい

ghtkn は今の AI coding workflow にかなり現実的な意味があります。Coding agent は gh で issue、PR、CI status を見たり、HTTPS で repository を clone / fetch したりします。最も簡単な方法は long-lived token を渡すことですが、それは permission boundary を壊しやすい方法でもあります。

ghtkn はより狭い入口を提供します。Token は short-lived、source は GitHub App、permissions は app と user の両方で制限され、default では local secure backend に保存されます。Agent command は wrapper 経由で一時的に token を取得でき、token を environment、config file、prompt に書き込む必要を減らせます。

もちろん、万能な automation solution ではありません。Device Flow は interactive なので unattended CI には向きません。README でも、GHTKN_ENABLE_DEVICE_FLOW=false を使うと background process が device flow で待ち続ける代わりに fast fail できると説明されています。

これはむしろ良い boundary です。Local development は interactive authorization を使える。CI では GitHub App installation token、OIDC、専用の secret management を使うべきです。Local tool をすべての environment に無理に押し込まない方が安全です。

使う前に limitations を確認する

GitHub App User Access Token は、すべての GitHub API use case を置き換えるわけではありません。README の limitations では、Packages API には classic PAT が必要であること、他 user の repository に write するのは難しいことが説明されています。Target repository に該当 App が installed されていなければ、PR creation のような操作はその token ではうまくいかないことがあります。

これは PAT との本質的な違いです。PAT は「ひとつの token に広い能力を持たせる」方向になりがちです。ghtkn は「各 capability を GitHub App installation と permission model に戻す」方向です。設定の手間は増えますが、failure reason は説明しやすくなり、leak radius も小さくなります。

Team で試すなら、まず read-only または low-risk use case から始めるのがよいです。Issue を読む、gh api で status を見る、public repo にアクセスする、personal repo で Git credential helper を試す。Flow が安定してから、write が必要な repository に明確な App permissions を設定する方が安全です。

まとめ

suzuki-shunsuke/ghtkn は narrow ですが engineering value の高い security tool です。GitHub App Device Flow で 8 時間の User Access Token を生成し、それを local backend に保存し、gh、Git credential helper、script が必要なときに取り出せるようにします。

すべての GitHub authentication problem を解決するわけではなく、CI の正式な secret management を置き換えるものでもありません。それでも、local machine、devcontainer、agent workspace が long-lived PAT に依存しているなら、ghtkn は試す価値があります。GitHub access の便利さを保ちながら、高リスクな token を長期間持つ習慣から一歩離れられます。