cnb-token

CNB アクセストークンの初期設定

「ユーザーが使用可能な CNB トークン、cnb CLI、パスワードなしの git を利用できるようにする」手順を標準化します。これは CNB ツールチェーン（リポジトリの作成、コミット、PR、パイプライン）の前提条件です。

完了の条件は、独立した 2 つの経路をそれぞれ開通させることです。

• CLI 経路：cnb <子命令> で API を呼び出せる（ユーザー情報の読み取りが 200）
• git 経路：https://cnb.cool/... への git push/pull でパスワードが不要

2 つの経路では認証情報の取得元が異なるため、一方を設定してももう一方が使えるとは限りません。

背景：cnb login を直接使えない理由

cnb login は OAuth2 デバイスフローを使いますが、取得した access_token にはデフォルトで group-resource:rw が含まれないため、 組織（group）内でのリポジトリ作成が 403 で拒否されます（errcode: 10023, Missing required scopes: group-resource:rw）。 個人の名前空間でも、scope が不足すると失敗する場合があります。

正しい方法：Personal Access Token (PAT) を使い、必要な認可スコープを明示的に選択したうえで、CNB_TOKEN 環境変数を通じて cnb CLI とその git-credential helper に渡します。

手順

1. cnb CLI をインストールする（必須の前提条件であり、任意ではありません）

git 認証情報ヘルパーには !cnb git-credential を設定します。実行可能ファイル cnb がないと、helper は何も通知せずに失敗し、 git は Git Credential Manager のポップアップにフォールバックするか、Authentication failed を報告します。以降の検証手順もすべて CLI に依存します。 そのため、まず CLI をインストールしてください。

# 跨平台统一（macOS / Linux / Windows 均可，走 npm 镜像加速）
npm install @cnbcool/cnb-cli -g

Windows では公式の PowerShell スクリプトも使用できます。

irm https://cnb.cool/cnb/skills/cnb-skill/-/git/raw/main/install.ps1 | iex

macOS / Linux：curl -fsSL https://cnb.cool/cnb/skills/cnb-skill/-/git/raw/main/install.sh | sh

インストール後、cnb --version で出力があれば確認完了です。コマンドが見つからない場合は、新しいターミナルを開く（PATH を更新する）か、npm のグローバル bin ディレクトリを確認してください。

2. 使用可能なトークンがすでにあるか確認する

最初からユーザーに新しいトークンの作成を求めないでください。まず確認します。

# 方式 A：环境变量里是否已有（CLI 优先读这个）
echo "CNB_TOKEN=${CNB_TOKEN:+已设置}"

# 方式 B：cnb CLI 是否已登录且能正常调用 API
cnb status            # 看是否“已登录”
cnb users get-user-info   # 能返回 200 说明 token 基本可用

判定：

• CNB_TOKEN がすでに設定されていて、第 5 歩の検証に合格する場合 → 作成せず、そのまま再利用し、ユーザーに「準備完了」と伝えます。
• ~/.cnb/token が存在していても、個人情報の読み取りにしか使えず、組織リポジトリの作成で 403 になる場合 → 引き続き、以下の PAT 作成手順を行う必要があります。

3. トークンがない場合 → 作成するよう案内する（案内のみ。ユーザーに代わって操作しない）

ユーザーに https://cnb.cool/profile/token を開いて → 添加访问令牌 を選択し、次の項目を明示的に選ぶよう案内します。

• 使用範囲：「私有」（組織／リポジトリ）を選択します。選択しない場合、プライベートリソースへの権限がデフォルトでありません。
• 認可スコープ（必要に応じて選択）：
  • group-resource:rw —— 組織内のリポジトリの作成／変更に必須（最もよくある 403 の原因はこれがないことです）
  • コードリポジトリの読み書き —— git push に必要です。
  • アーティファクトリポジトリ／OpenAPI などのその他のスコープ —— 今後の用途に応じて追加してください。
• トークン名は任意です（例：iao-cli、cnb-cli）。
• 有効期限は必要に応じて設定します（期限切れ後は再作成して setx が必要です）。

作成後、ユーザーにトークンをコピーして、こちらに貼り付けるよう伝えてください。

⚠️ セキュリティ：PAT は平文の秘密鍵です。公開の場に貼り付けないようユーザーに伝えてください。 このスキルでは設定に一時的に使用するだけで、リポジトリ内のファイルには書き込みません。漏えいが心配な場合は、使用後にトークンのページで取り消し、再作成してください。

4. トークンを永続化する

トークンを受け取ったら（これを <PAT> とします）、次の 3 つを行います。

(a) 環境変数 CNB_TOKEN に書き込む（CLI はこれを優先して読み取り、scope が不足している ~/.cnb/token 内の OAuth token を上書きします）

Windows（ユーザー単位。再起動後または新しいターミナルで自動的に反映されます）：

setx CNB_TOKEN "<PAT>"

その他のプラットフォーム：export CNB_TOKEN="<PAT>" を shell profile（例：~/.bashrc）に書き込むか、 CI でプラットフォームから注入します。

(b) 現在のセッションですぐに有効にする

setx が反映されるのは新しいプロセスのみです。現在の shell で手動で export CNB_TOKEN "<PAT>"（bash）を実行するか、PowerShell で $env:CNB_TOKEN = "<PAT>" を設定してください。そうしないと、このセッションの後続コマンドから読み取れません。

(c) git 認証情報ヘルパーを設定する（設定しないと push で引き続きパスワードが必要です）

git config --global credential.https://cnb.cool.helper '!cnb git-credential'

注意：helper の値には ! プレフィックスが必要です。付けないと git が cnb git-credential を git credential-cnb サブコマンドとして誤って解析し、エラーになります（git: 'credential-cnb' is not a git command）。 ! を付けると git はこれを shell コマンドとして実行します。CNB_TOKEN が存在する場合、cnb git-credential は username=cnb と password=<PAT> を返します。

5. 「完了」を検証する（経路ごとに確認）

2 つの経路では認証情報の取得元が異なるため、それぞれ個別に検証する必要があります。

# ── CLI 链路 ──
cnb users get-user-info        # 期望 status: 200，返回用户信息

# ── git 链路（用一个真实存在的公开/私有仓库测）──
git ls-remote https://cnb.cool/<组织>/<仓库>.git HEAD
# 期望：直接返回 commit hash，全程无弹窗、无 401

判定表：

現象	原因	対処
CLI は 200 だが、git が Authentication failed を報告する	helper が依存する cnb が PATH にない（CLI が未インストール、または新しいターミナルを開いていない）	手順 1 に戻って CLI をインストールする／ターミナルを開き直し、git 経路の検証を再実行する
git が Git Credential Manager のウィンドウを表示する	helper が何も通知せず失敗した場合のフォールバック動作	これは行き止まりではありません：ウィンドウの Username に cnb、Password に PAT を入力します。GCM が Windows 資格情報マネージャーに保存するため、以降はパスワード不要になります。入力後、ls-remote を再実行すれば確認できます
cnb git-credential get が unknown host を報告する	CLI サブコマンドが単独の host を解析する際の癖で、実際の push には影響しません	無視してください。git ls-remote の実測結果を基準にします
CLI が 401/403 を返し、scope 不足のメッセージが表示される	cnb login の OAuth token が残っていて読み取られている	現在のセッションで CNB_TOKEN が export 済みであることを確認します（手順 4b）

git 経路の検証に合格すれば、push/pull でパスワードが不要になります（helper が認証情報を返すか、GCM に認証情報が保存されているか、どちらか一方が機能すれば十分です）。

完了の条件（ユーザーへの案内文）

✅ CNB トークンの設定と永続化が完了しました：

• CNB_TOKEN が環境変数に書き込まれました（新しいターミナルで自動的に反映されます）
• cnb CLI がインストールされ、API 呼び出しは正常です
• git 認証情報ヘルパーが設定され、cnb.cool への push/pull でパスワードが不要になりました これで、トークンを再度貼り付けることなく、リポジトリの作成やコードのプッシュを実行できます。

注意事項

• ~/.cnb/token は残しておいて構いません：ここに保存されているのは cnb login の OAuth token です。CNB_TOKEN を設定すると優先されないため、削除は不要です。
• PAT の有効期限切れ：期限切れ後は、新しい PAT を使って setx CNB_TOKEN "<PAT>" を再実行すればよいです。
• 永続化の取り消し：setx CNB_TOKEN ""（Windows）を実行するか、システムのプロパティ → 環境変数で削除します。トークンの取り消しは cnb.cool/profile/token で行います。
• GCM に保存済みの認証情報の置き換え：資格情報マネージャーに古い PAT が保存されている場合、新しいトークンに変更しても git が古い値を読み取ることがあります。 Windows での手順：コントロール パネル → 資格情報マネージャー → Windows 資格情報 → git:https://cnb.cool の項目を削除します。次回の操作時に新しい認証情報が取得されます。