agenteye-enterprise GitHub 組織から配布されます。組織にアクセス権が付与されたら、各開発者またはオペレーターが自分のトークンを生成・ローテーションするため、アクセスはユーザーごとに監査・失効が可能です。
マシンごとに1回、トークンを環境変数と Docker 認証情報として設定します:
ユーザー名について: GHCR はdocker loginのユーザー名を無視し、トークンのみで認証するため、空でない値であれば何でも機能します。このドキュメントでは簡潔さのために-u xを使用しています。Kubernetes のイメージプルシークレットを作成するデプロイメントマニフェストでは、agenteye-enterpriseのようなより分かりやすいユーザー名を使用することもあります。どちらも受け付けられます。
オプション A: クラシックトークン（推奨）
GHCR のdocker login およびイメージプローのフローはクラシックトークンに対して最も広く、一貫したサポートを提供しているため、クラシックトークンは AgentEye に最も信頼性の高い選択肢です。必要なものはすべて2つのスコープでカバーされ（イメージのプルとリリースアセットのダウンロード）、一度認証すれば、レジストリの問題をトラブルシューティングすることなく作業を進められます。そのうちの1つ read:packages は真に読み取り専用ですが、もう1つの repo はプライベートなリリースアセットへのアクセスを許可する唯一のクラシックスコープであり、意図的に広範な権限を持っています。GitHub はこれをプライベートリポジトリへの完全な制御（読み取りと書き込み）として定義しています。
1. トークンの作成
GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic) に移動します。| フィールド | 値 |
|---|---|
| Note | agenteye-<マシン名またはチーム名>（例: agenteye-prod-server） |
| Expiration | セキュリティポリシーに適した有効期限を設定してください。90日が合理的なデフォルトです |
ラベルについて: GitHub はクラシックトークンではこのフィールドを Note、細粒度トークンでは Token name と表示しますが、どちらも同じ目的を果たします: 後の監査と失効のための人間が読みやすい識別子です。
2. スコープの選択
| スコープ | 必要な理由 |
|---|---|
read:packages | ghcr.io/agenteye-enterprise/ から Docker イメージをプルし、パッケージアセットをダウンロードする |
repo | agenteye-enterprise/releases からプライベートリポジトリのコンテンツ、生ファイル、リリースアセットを読み取る。これは GitHub の広範な「プライベートリポジトリへの完全な制御」スコープ（読み取りと書き込み）であり、読み取り専用スコープではありませんが、プライベートなリリースアセットへのアクセスを許可する唯一のクラシックスコープです |
3. トークンの生成とコピー
Generate token をクリックし、表示された値をすぐにコピーしてください。表示されるのは一度だけです。シークレットマネージャーまたは環境に保存してください。オプション B: 細粒度トークン
細粒度トークンは特定のリポジトリと権限にアクセスを限定するため、最小権限の原則に最も適した選択肢です。組織のセキュリティポリシーで細粒度トークンが義務付けられている場合はこちらを選択してください。注意: GHCR の細粒度トークンのサポートはクラシックトークンほど一貫していません。これらの手順に従った後でdocker loginやdocker pullが失敗する場合は、クラシックトークン（オプション A）にフォールバックしてください。
1. トークンの作成
GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token に移動します。| フィールド | 値 |
|---|---|
| Token name | agenteye-<マシン名またはチーム名>（例: agenteye-prod-server） |
| Expiration | セキュリティポリシーに適した有効期限を設定してください。90日が合理的なデフォルトです |
| Resource owner | agenteye-enterprise |
| Repository access | Only select repositories → agenteye-enterprise/releases |
2. リポジトリ権限の設定
Permissions → Repository permissions で以下を設定します:| 権限 | アクセス |
|---|---|
| Contents | Read-only |
| Packages | Read-only |
注意: コンテナイメージ（ghcr.io/agenteye-enterprise/...）がリポジトリにリンクされたパッケージではなく、組織レベルのパッケージとして公開されている場合、リポジトリスコープの権限だけでは Docker ログインが失敗する可能性があります。その場合は、組織レベルの権限を追加してください: Permissions → Organization permissions → Packages: Read-only。
3. 各権限で許可される操作
| 権限 | 用途 |
|---|---|
| Contents: Read-only | agenteye-enterprise/releases から docker-compose.yml、リリースバイナリ、Python ホイールをダウンロードする |
| Packages: Read-only | ghcr.io/agenteye-enterprise/ から Docker イメージをプルする |
4. トークンの生成とコピー
Generate token をクリックし、表示された値をすぐにコピーしてください。表示されるのは一度だけです。シークレットマネージャーまたは環境に保存してください。トークンのローテーション
定期的にトークンをローテーションすることで、アクセスの監査性が保たれ、認証情報が漏洩した場合の影響範囲を限定できます。トークンはいつでも期限切れや失効が発生する可能性があるため、ローテーションは認証を維持するための通常の手順です。ローテーションの手順:- 上記の手順で新しいトークンを生成します。
- 環境またはシークレットマネージャーの
AGENTEYE_TOKENを更新します。 - Docker を再認証します:
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin - GitHub → Settings → Developer settings → Personal access tokens で古いトークンを失効させます。トークンの種類に合わせて Tokens (classic) または Fine-grained tokens のサブページを開き、削除してください。
トークンの確認
デプロイメントに組み込む前にトークンが正常に動作することを確認してください。これにより、認証エラーをデプロイ中ではなくこの段階で検出できます。各コマンドで上記のスコープの1つを確認します:docker login が成功すればパッケージスコープが確認でき、ファイルがダウンロードされればコンテンツスコープが確認できます。
トラブルシューティング
| 症状 | 考えられる原因 | 対処法 |
|---|---|---|
docker login が 401 を返す | トークンに Packages: Read-only（細粒度）または read:packages（クラシック）が不足している | パッケージスコープを追加して再生成する |
GitHub の生 URL で curl が 404 を返す | トークンに Contents: Read-only または repo スコープが不足している | コンテンツスコープを追加して再生成する |
gh release download が 403 を返す | トークンが agenteye-enterprise/releases に対して承認されていない | 細粒度トークンのリポジトリアクセスにそのリポジトリが含まれているか確認するか、repo スコープを持つクラシックトークンを使用する |
| トークンは受け付けられるがイメージが見つからない | 細粒度トークンに組織レベルのパッケージ権限がない | 組織レベルの Packages: Read-only 権限を追加する |
support@exosphere.host までお問い合わせください。