GitHub Codespaces (Blank) でリポジトリ未作成のままGit管理を始める手順と、GITHUB_TOKEN権限エラーの対処法
概要
AIツール（Claude等）で生成したコードを、GitHubリポジトリがまだ無い状態からGitHub Codespacesに持ち込んでGit管理下に置くまでの手順をまとめる。
途中、Codespaces環境特有のGITHUB_TOKEN権限エラーで2箇所詰まったので、その原因と対処法を中心に記載する。
前提
- GitHubアカウントを持っている
-
gh（GitHub CLI）が使える環境（Codespacesにはデフォルトで入っている） - リポジトリはまだ存在しない
1. Blank Codespaceを作成する
GitHub CodespacesはリポジトリなしでもBlank状態で起動できる。
-
https://github.com/codespacesを開く - 「New codespace」をクリック
- リポジトリ選択でBlankを選択
これでどのリポジトリにも紐づかない開発環境が起動する。
Codespaceは既定で30分操作がないと自動停止し、停止後は既定30日間再開しないと自動削除される（アイドルタイムアウト・Retention periodともに個人設定で変更可能）。作業を始めたら早めにリポジトリへ紐付けておくと安心。
2. ファイルを配置する
エクスプローラーパネルへファイルやzipをドラッグ&ドロップでアップロードし、必要であれば展開する。
unzip project.zip -d .
rm project.zip
.gitignoreを用意し、.env（APIキー等の秘匿情報）、node_modules、ローカルDBファイル等がコミット対象に含まれないようにしておく。
3. Gitリポジトリを初期化してコミット
git init
git add .
git status # .env や node_modules 等が含まれていないか確認
git commit -m "Initial commit"
4. GitHubリポジトリを作成してpush
gh repo create <repo-name> --private --source=. --remote=origin
git push -u origin main
ここで2種類のエラーに遭遇した。
トラブルシューティング
エラー1: リポジトリ作成時の権限エラー
GraphQL: does not have the correct permissions to execute `CreateRepository` (createRepository)
原因
Codespacesは起動時にGITHUB_TOKENという環境変数へ、そのCodespaceのリポジトリ操作用に発行された制限付きトークンを自動的にセットする。このトークンにはリポジトリ新規作成の権限が含まれていないため、gh repo createが失敗する。
対処
環境変数をクリアしてから、ghを個人アカウントの認証情報で再ログインする。
unset GITHUB_TOKEN
gh auth login
gh auth loginのプロンプトでは以下を選択する。
GitHub.comHTTPSLogin with a web browser
これでブラウザ側の認証フローに切り替わり、個人アカウントの通常の権限でghが動作するようになる。
gh auth refresh -h github.com -s repoでスコープを追加する方法もあるが、GITHUB_TOKENが環境変数に残っている間はそちらが優先されるため、上記のunsetを先に行う必要がある。
エラー2: push時の403エラー
remote: Write access to repository not granted.
fatal: unable to access 'https://github.com/<user>/<repo>.git/': The requested URL returned error: 403
原因
gh auth loginでCLI側の認証情報を切り替えても、gitコマンドが実際に使用するcredential helperの設定は自動では更新されない。そのためgit pushは依然として古い（権限不足の）認証情報を参照し続ける。
対処
unset GITHUB_TOKEN
gh auth setup-git
git push -u origin main
gh auth setup-gitが、gitのcredential helperを現在ログイン中のghアカウントに紐付け直す。これによりpushが個人アカウントの権限で実行されるようになる。
確認コマンド
認証状態がおかしい場合は以下で確認できる。
gh auth status
想定と異なるアカウントやスコープになっていれば、gh auth logout → gh auth loginからやり直す。
なお、組織（Organization）アカウント配下でメンバーによるリポジトリ作成を禁止するポリシーが設定されている場合、上記の対処では解決しない。個人アカウント配下で作成するか、Organizationの管理者に権限付与を依頼する必要がある。
運用ルール: 仕様の正本（Source of Truth）をどこに置くか
チャットで設計・Codespaces内Claude Codeで実装、という分業をする場合、「今どの仕様が正しいか」の置き場所を決めておかないと、判断がチャット履歴に散らばって参照できなくなる。
以下のルールで運用している。
- リポジトリ内に
docs/SPEC.mdを置き、これを仕様の正本とする - 仕様変更の判断はチャット（設計側）で行い、決定したら
docs/SPEC.mdに反映する - Codespaces側のClaude Codeは
docs/SPEC.mdに従って実装する。他のドキュメント（README、タスク一覧等）がSPEC.mdと食い違っている場合は、Codespaces側でSPEC.mdに合わせて機械的に修正してよい - ただし、
SPEC.mdの内容自体を変更する判断はCodespaces側で行わない。実装中に仕様の解釈に迷うケースが出た場合は、チャット側に持ち帰って判断する
この境界はCLAUDE.mdに明文化しておくと、Claude Codeが自発的に守るようになる。
詳細な仕様は`docs/SPEC.md`にまとめてある。ここが正。
コードを変更する前に、関連する仕様が`docs/SPEC.md`と食い違っていないか確認すること。
補足: タスク管理はファイルではなくGitHub Issuesに寄せる
同様の理由で、開発タスクも自作のdocs/ISSUES.mdのようなファイルで管理するより、GitHub Issues（Label・Milestone）に寄せる方が運用コストが低い。理由は以下。
- Markdownファイルは更新を手動で行う必要があり、実装との食い違いが放置されやすい
- GitHub Issuesはクローズ管理・検索・Milestoneでの進捗管理が標準で使える
-
ghCLIで一括登録できるため、既存のMarkdownからの移行コストも低い
移行時はgh label create・gh api repos/:owner/:repo/milestones・gh issue createを組み合わせたスクリプトをCodespaces上で一度実行すればよい。移行後は元のMarkdownファイルをgit rmし、README.md・CLAUDE.mdの参照もGitHub Issuesへのリンクに更新する。
まとめ：詰まらない最短手順
エラーの原因はどちらもGITHUB_TOKEN環境変数によるものなので、最初に認証まわりを片付けてしまうのが早い。
git init
git add .
git status
git commit -m "Initial commit"
unset GITHUB_TOKEN
gh auth login
gh auth setup-git
gh repo create <repo-name> --private --source=. --remote=origin
git push -u origin main
Codespaces特有の自動認証（GITHUB_TOKEN）は、そのCodespaceで既存リポジトリを操作する分には便利だが、新規リポジトリの作成やpushには権限が不足するという点を覚えておくとよい。