権限・認証・環境変数

認証を3つの境界に分ける

確認単位。 1つのtokenが見つかっても他の境界が通るとは限りません。GitHub API、push、providerを個別に確認します。

推奨はlocalの対話実行から始める

通常の端末では、GitHub credentialを1つ、採用するproviderの認証を1つ用意します。Issue起点の無人運用は前提にしません。

1. 01
   GitHubを認証

   specrunner loginのDevice Flow、または既存のgh auth loginを使います。

2. 02
   providerを認証

   AnthropicはClaude Codeの対話認証、OpenAIはcodex loginを使います。

3. 03
   run前に診断

   doctorのrequired failureを解消し、実repoへのpush・PR権限も確認します。

npx specrunner login
# Anthropic local: Claude Codeで対話認証
# OpenAI local:
codex login
npx specrunner doctor

headlessだけtokenを明示します。 Claude localを対話なしで動かす場合はclaude setup-token後にspecrunner login --provider claudeで保存できます。OpenAIはOPENAI_API_KEY、GitHubはGH_TOKENを実行環境へ渡します。

providerとruntimeの対応範囲、built-in model、混成時の制約は対応プロバイダーを参照してください。

GitHubは操作に必要な権限だけを渡す

doctorは実操作の権限までは証明しません。 現行checkはtokenの存在とGitHub APIでの有効性を確認します。対象repoへのpush、PR作成、merge可否は実際のrepository policyに依存します。

HTTPS originではtokenをremote URLやglobal git configへ保存せず、transport commandのextraheaderへ限定して渡します。plain HTTPには注入せず、SSH originは変更しません。

同じcredentialは決められた順で解決する

managedだけcredentials.jsonが環境変数より先です。 SPECRUNNER_API_KEYは保存済みanthropic.apiKeyのfallbackです。一方、現行loginが保存できるproviderはgithubとclaudeだけなので、managedの初期設定は環境変数を使うのが明確です。

runtimeごとの環境変数

既定値。 heartbeatはTTYで30秒、non-TTYで60秒です。progress.heartbeatIntervalSecが環境変数より優先します。

名前が似ていても代替にならない変数があります。 現行OpenAI runnerが読むのはOPENAI_API_KEYです。doctorのhintに残るCODEX_API_KEYはrunnerへ渡されません。managedもANTHROPIC_API_KEYではなくSPECRUNNER_API_KEYを解決します。

SPECRUNNER_GITHUB_CLIENT_IDはbuilt-in GitHub App client IDのtest・advanced overrideです。通常運用では設定しません。XDG_STATE_HOMEのresolverはありますが、現行job・log stateはrepo内.specrunner/へ保存されます。

managedはGitHub tokenとAnthropic keyを分ける

SPECRUNNER_API_KEYはmanaged agentとenvironmentの作成・実行に使います。GitHub APIとpushには、別途GitHub tokenが必要です。

export GH_TOKEN=...
export SPECRUNNER_API_KEY=...
npx specrunner managed setup
npx specrunner managed status
npx specrunner doctor

secretは子processへ自動継承させない

SpecRunnerは*_TOKEN、*_API_KEY、*_SECRETに一致する環境変数をsubprocessとSDKの継承envから除外し、必要なcredentialだけを専用の経路で渡します。

任意名のsecretを過信しません。 denylistとsuffix patternで継承を止めますが、秘密値を通常変数名へ入れれば検出できません。secretは*_TOKEN、*_API_KEY、*_SECRETの命名とcredential storeへ寄せます。

run前に4点を確認する

1. 01
   解決元

   doctorでGitHub、Claude、managed credentialのsourceを確認。

2. 02
   provider

   採用modelに対応するCLIまたはAPI keyが利用できるか確認。

3. 03
   repository

   origin hostとtoken hostが一致し、branchをpushできるか確認。

4. 04
   state path

   .specrunner/localとworktreeを作成できる権限があるか確認。

npx specrunner doctor
npx specrunner doctor --json
git remote get-url origin
git status --short

実行条件。 tokenの存在だけでなく、正しいhost・provider・repository権限・書込pathが揃った場合にrunへ進みます。