/web-setupのworkflow scope警告の意味と直し方 — Claude Code
/web-setupが出すworkflowスコープの警告は、ghトークンにワークフローファイルを変えるpushの権限が無いという意味です。gh auth refreshでの直し方と、警告を残してよい場合を解説します。
警告は「ghトークンにworkflowスコープが無い」という意味
/web-setupを実行したときに、GitHub CLIのトークンにworkflowスコープが無いと警告されることがあります。警告が出ても続行はできます。ただし、そのトークンを使うクラウドセッションでは、GitHub Actionsのワークフローファイルを変更するpushなど、一部のpushがGitHubに拒否されることがあります。
直し方は2手順です。シェルでgh auth refresh -s workflowを実行し、そのあとClaude Code CLIで/web-setupをやり直します。
gh auth refresh -s workflow/web-setupはシェルのコマンドではなく、claudeを起動したプロンプトの中で打つスラッシュコマンドです。gh auth refreshと/web-setupでは実行する場所が違う点が、最初につまずきやすいところです。/web-setupそのものの仕組みと、GitHub Appとの違いはClaude Code WebのGitHub認証にまとめています。この記事は、警告の意味と対処に絞ります。
警告が出る流れ
/web-setupは、gh auth tokenが出力するトークンを読み取り、送信してよいかの確認を経て、そのトークンをAnthropicに送ります。Anthropicはトークンをclaude.aiアカウントに紐づけて暗号化して保存し、クラウドセッションのGitHubアクセスに使います。自分で起動したクラウドセッションは、そのトークンが見られるリポジトリならGitHub Appのインストールなしで扱えます。
つまりクラウドセッションがGitHubに対して持つ権限は、手元のghトークンの権限そのものです。トークンに付いているスコープが足りなければ、クラウド側でもその操作はできません。警告は、送る前の時点でその不足を知らせるものです。
警告を読むときの3つの前提
警告が出るのは/web-setup側
ブラウザーでGitHub Appを認可する方式は、手元の
ghトークンを使いません。この警告はghトークンを送る方式に固有です。止まらずに続行できる
警告は拒否ではありません。コマンドは続行でき、接続自体は完了します。
影響が出るのは特定のpush
ワークフローファイルを変える操作などで、GitHubが拒否することがあります。通常のコード変更のpushとは別の扱いです。
workflowファイルのpushだけ拒否される理由
GitHubのOAuthスコープの一覧では、workflowは「GitHub Actionsのワークフローファイルを追加・更新する権限」と説明されています。ほかのコード変更は、ghが最低限持つスコープ(repo、read:org、gist)の範囲で足ります。.github/workflows/配下のファイルだけは、追加でこのスコープが要ります。
例外も1つ書かれています。同じパスで同じ内容のファイルが同じリポジトリの別のブランチにすでにあれば、スコープが無くてもコミットできます。新規ファイルの追加や内容の変更でなければ、拒否されない場合があるということです。
ワークフローファイルが特別扱いされる理由として、GitHubの説明はワークフローファイルがGITHUB_TOKENを露出しうることを挙げています。GITHUB_TOKENが持つスコープは、OAuthトークンとは別の設定です。
クラウドセッションの視点では、次のように現れます。
| クラウドセッションの操作 | workflowスコープなしのghトークン |
|---|---|
| 通常のソースコードを変更してブランチをpush | workflowスコープなしのghトークン通る |
.github/workflows/のYAMLを追加・変更してpush | workflowスコープなしのghトークンGitHubに拒否されることがある |
| 同じパス・同じ内容のファイルが別ブランチにある状態でpush | workflowスコープなしのghトークンスコープ無しでもコミット可能 |
表の3行目は、GitHubのスコープ説明にある例外の再掲です。クラウドセッションがその条件を満たす状況に当たるかは、ブランチの状態次第です。
直す手順
workflowスコープを足して/web-setupをやり直す
- 1
シェルでスコープを足す
gh auth refresh -s workflowを実行します。-sは--scopesの短縮形で、「ghが持つスコープに追加する」スコープをカンマ区切りで渡します。ブラウザーが開くので、承認します。 - 2
claudeを起動して/web-setupを実行する
シェルから
claudeを起動し、プロンプトで/web-setupと入力します。確認のプロンプトに答えると、更新後のトークンがclaude.aiアカウントに送り直されます。 - 3
Connected asの表示を確認する
成功すると
Connected as <GitHubユーザー名>と表示され、claude.ai/codeがブラウザーで開きます。
手順1だけでは足りません。ghのトークンが更新されても、claude.aiアカウントに保存済みのトークンは古いままだからです。クラウド側に反映するには、必ず/web-setupをやり直します。
gh auth refreshは、スコープを指定しなければ、すでに付与されているスコープを維持します。workflowを足しても、既存のスコープが消えることはありません。
Organizationのリポジトリでは追加の承認が出ることがある
SAMLシングルサインオンを強制しているOrganizationのリポジトリでは、ghのトークンがそのOrganizationに対して未承認のことがあります。この場合のGitHub側の案内は、/install-github-appのSSO警告に載っています。同じ症状でrepoとworkflowの両方を足す例として、次のコマンドが示されています。
gh auth refresh -h github.com -s repo,workflow-h github.comは、認証するGitHubのホストを指定する--hostnameの短縮形です。GitHub Enterprise Serverのような別ホストを使っているなら、ここを自分のホストに替えます。コマンドを実行すると、GitHubがSSOの承認を求めることがあります。SSOの詳細は、GitHub Actions連携のOrganization設定と合わせて読むと流れがつかめます。
警告を残したままでよい場合、直しておくべき場合
警告は「続行できる」ので、無理に直さなくてよいケースもあります。切り分けは、クラウドセッションにワークフローファイルを触らせるかどうかです。
workflowスコープを足すかどうか
足さない
クラウドセッションでは.github/workflows/に触れない運用です。アプリケーションコードの修正やテスト追加だけを任せるなら、スコープが無くてもpushに支障はありません。
足す
CIの設定ごと直したい、Actionsのバージョンを上げさせたいなど、ワークフローのYAMLもクラウドセッションに変更させる運用です。スコープが無いと、そのpushがGitHubに拒否されることがあります。
スコープは、後から外せます。gh auth refresh --remove-scopes workflowで削除でき、処理は冪等です。足しておいて、不要になったら外すという使い方が成り立ちます。外したあとは、/web-setupを再実行しないとクラウド側のトークンは更新されません。ghの最小スコープ(repo、read:org、gist)は外せません。
スコープを足さずに済ませたい場合の指示
ワークフローには触らせたくないが、うっかり変更してpushが拒否される事態も避けたい場合は、クラウドセッション側のリポジトリにルールを置く手があります。プロジェクトのCLAUDE.mdに、次のような一節を書く例です。
## GitHub Actions
- `.github/workflows/` 配下のファイルは変更しない。
- ワークフローの修正が必要だと分かったら、変更案を PR の説明文に書くだけにして、
ファイル自体は編集しない。これはGitHub側の制限を回避する手段ではなく、拒否される操作をそもそも試さないための運用です。同じ場所に「ワークフローの変更は人が手元で行う」と書いておけば、PRのレビューで変更案だけを受け取れます。ワークフローYAMLをClaude Codeに書かせる側の手順は、Claude CodeでGitHub ActionsのワークフローYAMLを書くで扱っています。
似た症状との切り分け
/web-setupまわりの不具合は、メッセージごとに原因が違います。workflowスコープの警告と取り違えやすいものを並べます。
| 表示 | 原因 | 対処 |
|---|---|---|
workflowスコープが無いという警告 | 原因ghトークンのスコープ不足 | 対処gh auth refresh -s workflowのあと/web-setupをやり直す |
Not signed in to Claude. Run /login first. | 原因CLIに有効なclaude.aiのサインインが無い。期限切れの場合もある | 対処/loginでclaude.aiアカウントにサインインして/web-setupを再実行 |
No commands match "/web-setup"、Unknown command: /web-setup | 原因APIキーやサードパーティプロバイダー認証で使っている、Team・EnterpriseでQuick setupがオフ、組織がクラウドセッションを無効化、ZDR・HIPAA構成など | 対処認証方式を/loginで切り替える、またはOwnerにQuick setupを確認する |
| クラウドセッションにリポジトリが出ない | 原因ghトークンでそのリポジトリが見えていない、またはghのアカウントを切り替えた | 対処gh repo view OWNER/REPOで見えるか確認し、見えるなら/web-setupをやり直す |
警告と、コマンド自体が出てこない問題は別です。警告が出たということは、/web-setupは実行できています。逆に「Unknown command」の場合は、スコープ以前にコマンドが使える条件を満たしていません。
補足: トークンの扱い
workflowスコープを足したトークンは、足す前より強い権限を持ちます。/web-setupで送るトークンは、クラウドセッションが取り扱えるすべてのリポジトリに対する権限として働きます。スコープを足すのは、ワークフローの変更をクラウドセッションに任せたいときに限る、という使い分けがあります。
トークンをclaude.ai側から消したいときは、claude.aiのConnectors画面でGitHubを切断します。トークンそのものを無効にするなら、GitHubのSettings > Applications > Authorized OAuth Appsで「GitHub CLI」のエントリを取り消します。取り消すと手元のghもサインアウトされ、再びgh auth loginと/web-setupが必要になります。
まとめ
workflowスコープの警告は、クラウドセッションでワークフローファイルを変えるpushが拒否されうる、という予告です。ワークフローを触らせないなら警告のまま続行でき、触らせるならgh auth refresh -s workflowのあとに/web-setupをやり直します。gh側だけを更新しても、claude.aiに保存されたトークンは古いままという点が、直し忘れの原因になります。