Claude Code Actionを設定しようとして以下のようなエラーに遭遇したことはありませんか？
│ Reason: GitHub Actions setup failed │
│ │
│ How to fix: │
│ • Check that you have the necessary permissions │
│ • Ensure your GitHub token has workflow scope: gh auth refresh -h github.com -s workflow │
│ • Try the manual setup instructions if this persists │
もしくは、/install-github-appコマンドをclaudeで実行せずにセットアップを試みた場合に、GitHub Actionsが権限エラーでfailしたことがある方もいらっしゃるかと思います。
Failed to setup GitHub token: Error: User does not have write access on this repository.
If you instead wish to use this action with a custom GitHub token or custom GitHub app, provide a `github_token` in the `uses` section of the app in your workflow yml file.
この記事では、これらのエラーの解決方法と背景について解説します。
tl;dr
1つ目のエラーメッセージに記載されていますが、以下のコマンドで認証しなおしましょう。
gh auth refresh -h github.com -s workflow
どちらのエラーについても、このコマンドを実行しなおした後で、ローカルにてセットアップしたいリポジトリのディレクトリに移動して/install-github-appを実行することで解消されました。
何が起きているのか
Claude Code ActionはGitHub Actionsのワークフローを自動で設定するため、GitHubトークンにworkflowスコープが必要です。しかし、gh auth loginでGitHub CLIを初期認証した際には、このスコープは含まれていません。
なぜgh auth loginだけでは不十分なのか
デフォルトスコープの制限
gh auth login実行時に付与されるデフォルトスコープ：
-
repo- リポジトリへの読み書き -
read:user- ユーザー情報の読み取り -
read:org- Organization情報の読み取り
workflowスコープが別途必要な理由
workflowスコープは特に強力な権限で、以下の操作を可能にします：
- GitHub Actionsワークフローの作成・編集・削除
- CI/CDパイプラインの制御
- デプロイメントの実行
セキュリティの観点から、初期認証時には含まれず、必要な時に明示的に追加する設計になっています。
解決手順
1. スコープの追加（推奨）
gh auth refresh -h github.com -s workflow
2. 現在のスコープ確認（オプション）
gh auth status
3. Claude Code Actionの再実行
スコープ追加後、Claude Code Actionのセットアップを再実行してください。
これでセットアップエラーやGitHub Actionsの実行エラーが解消されるはずです。
まとめ
Claude Code Actionのセットアップエラーは、GitHubトークンのworkflowスコープ不足が原因であることがあります。この場合、gh auth refresh -s workflowで簡単に解決できますので、ひとまずはこのコマンドを試してみてください。
あと、セットアップをする際は、大人しくドキュメントの指示にあるようにclaudeコマンドの/install-github-appを実行するやり方にしましょう。
Discussion