mcpField
G
glab-auth

glab-auth

github.com/vince-winkintel開発49132 回インストール1 日前に更新
リポジトリ

glab-auth について

glab-authはGitLab CLIの認証を管理するスキルです。複数のGitLabホストを利用する個人や自動化向けに、ログイン、認証情報の保存、状態確認、IDの分離を扱います。

主な機能

  1. 01対話型・非対話型ログイン
  2. 02ホスト別のJSON認証状態確認
  3. 03Git認証ヘルパーの設定
  4. 04キーチェーンまたは設定ファイルでの認証情報保存
  5. 05複数アカウントのID分離に関する注意

活用シーン

  1. 01GitLabホスト向けのglab設定
  2. 02自動化での認証状態確認
  3. 03HTTP(S) Git認証アクセスの設定
  4. 04エージェントによるGitLab書き込みのID分離

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/vince-winkintel/gitlab-cli-skills --skill glab-auth

インストール後、Claude Code で/glab-authを入力して読み込まれたか確認します。

同梱ファイルreferences/commands.md

詳細

glab auth

GitLab CLI の認証を管理します。

非対話型の Git 認証ヘルパー

glab auth login --setup-git-credential-helper は、確認を求めずに glab をホスト固有の Git 認証ヘルパーとして設定します。これはそのホストのグローバルな Git 設定を変更するため、ログインだけでなく、この設定変更についても承認を得てください。HTTP(S) に適用されます。SSH を優先する設定でも、HTTPS ヘルパーが登録されます。トークンをコマンド引数に指定するのではなく、--stdin を優先してください。

glab auth login --hostname gitlab.example.com --stdin --setup-git-credential-helper < token.txt

承認済みのトークンファイルは Git の管理対象外かつログの出力先外に保管してください。キーリングのエントリーが見つからない場合は、通常の認証情報解決に従います。キーリングがロックされている、アクセスが拒否される、または利用できない場合は、エラーが報告されます。使用可能なトークンが残っていない場合は、対象のホストに再認証してください。ID を黙って切り替えたり、保存方法の安全性を下げたりしないでください。

クイックスタート

# Interactive login
glab auth login

# Browser/OAuth login without the prompt
glab auth login --hostname gitlab.com --web

# Check current auth status
glab auth status

# Login to different instance
glab auth login --hostname gitlab.company.com

# Logout
glab auth logout

ワークフロー

認証状態の機械可読な出力
glab auth status --hostname gitlab.example.com --output json
glab auth status --all --output json
glab auth status --all --output json --jq '.hosts[] | {host, state, user}'

JSON には hosts 配列が含まれ、ホストごとの状態、ユーザー（取得可能な場合）、エンドポイント、プロトコル、トークンの取得元、警告、およびエラーのメタデータが格納されます。トークン自体は含まれず、JSON 出力で --show-token を指定すると拒否されます。省略された任意のフィールドを、認証情報が空であると誤解しないでください。書き込みを行う前に、終了ステータスと各ホストの状態の両方を確認し、対象のユーザーを glab api user で別途検証してください。--jq は必ず --output json と組み合わせてください。

初回セットアップ
  1. glab auth login を実行します
  2. 認証方法（トークンまたはブラウザー）を選択します
  3. GitLab インスタンスに関するプロンプトに従います
  4. glab auth status で確認します

glab auth login は、セットアップを一通り行うフローに対応しています。

  • --api-host を指定すると、セルフホスト型インスタンスの API／Web エンドポイントを別のものに明示的に設定できます
  • --ssh-hostname を指定すると、セルフホスト型インスタンスの SSH エンドポイントを別のものに明示的に設定できます
  • --web を指定すると、ログイン方式の選択プロンプトを省略して、ブラウザー／OAuth 認証に進みます
  • --container-registry-domains を指定すると、ログイン時にレジストリ／依存関係プロキシのドメインを事前設定できます

例：API ホスト名が gitlab.company.com、SSH ホスト名が ssh.company.com

パーソナルアクセストークンの場合、glab には少なくとも api と write_repository が必要です。GitLab 18.9 では https://<host>/-/user_settings/personal_access_tokens/legacy/new?scopes=api,write_repository が導入されました。このルートは、それ以前のリリースには存在しません。GitLab 18.8 以前では、代わりに https://<host>/-/user_settings/personal_access_tokens?scopes=api,write_repository を使用します。旧バージョンのセルフマネージドサーバーに現在の GitLab.com のルートが存在すると決めつけず、対象インスタンスの URL を使用してください。

非対話型ログインで --hostname を省略した場合、対象は次の順に解決されます。ベースリポジトリの GitLab リモート、GITLAB_HOST、設定の host、gitlab.com。認証情報を書き込む際、周囲のリポジトリや環境が意図的に信頼できる情報源として設定されていない場合は、明示的な --hostname を指定してください。

対話型ログインでは、環境変数に基づく設定値は、対応するセットアップの質問と同じ経路の場合に限り、その回答として事前入力されます。GITLAB_HOST はリモートの検出より先にインスタンスを選択します。ホスト名が --hostname または GITLAB_HOST から取得される場合、GITLAB_API_HOST と GITLAB_SSH_HOST は対応するエンドポイントの質問を省略します。インスタンスメニューで「GitLab Self-Managed or GitLab Dedicated instance」の経路を選択した場合は、--api-host と --ssh-hostname を指定しない限り、glab は引き続きエンドポイントのホスト名を尋ねます。GLAB_CONTAINER_REGISTRY_DOMAINS、GLAB_GIT_PROTOCOL、GLAB_API_PROTOCOL は、それぞれレジストリドメインとプロトコルに関する質問を省略します。1 回限りの認証情報の書き込みには、明示的なコマンドフラグの方が分かりやすいため、シェルの状態を厳密に管理していない場合は、そちらを優先してください。

GitLab Self-Managed または GitLab Dedicated へのブラウザー／OAuth ログインで、OAuth アプリケーション ID が設定されていない場合、glab は対話型のセットアップを案内するようになりました。既存の Application ID を貼り付けるか、インスタンス／グループの管理者向けに登録に必要な値を正確に表示するかを選択します。「管理者が作成するために必要な情報を表示する」を選ぶと、リダイレクト URI、スコープ、Confidential: off の要件のみが表示され、その後、同じ「まず client_id を設定してください」というエラーが表示され、ログイン試行はゼロ以外の終了コードで終了します。管理者がアプリケーションを作成したら、glab config set client_id <client_id> -g --host <hostname> で ID を保存するか、GITLAB_CLIENT_ID をエクスポートしてから、ログインを再実行してください。登録値を表示しても、同じログイン試行を続行できるわけではありません。Application ID のプロンプトにアプリケーションシークレットを貼り付けないでください。新たに貼り付けた ID は、OAuth の往復処理が成功した後にのみ保存されます。非対話型環境では、glab config set client_id <client_id> -g --host <hostname> で明示的に事前設定するか、GITLAB_CLIENT_ID を指定してください。

ログインフラグの例

--token または --stdin を使ったトークンログインでは、選択したホストのコンテナレジストリドメインも保存されます。値の解決では、明示的な --container-registry-domains、設定値（環境変数に基づく設定を含む）、ホスト名から導出されるデフォルトの順に優先されます。これにより、再ログイン時にもカスタムドメインが維持され、Docker 認証情報ヘルパーで利用できるようになります。Docker を設定する前に、glab config get container_registry_domains --host <hostname> で確認してください。この保存動作はパーソナルトークンの経路に適用されます。別の --job-token の経路にも同じセットアップ動作があると決めつけないでください。

# Personal-token login with explicit registry domains; keep the token file outside Git
glab auth login --hostname gitlab.company.com --stdin \
  --api-protocol https --git-protocol ssh \
  --container-registry-domains "registry.gitlab.company.com,gitlab.company.com" \
  < approved-token-file
glab config get container_registry_domains --host gitlab.company.com

# Self-managed GitLab with separate API and SSH endpoints
glab auth login \
  --hostname gitlab.company.com \
  --ssh-hostname ssh.company.com

# Skip prompts and go straight to browser/OAuth auth
glab auth login --hostname gitlab.com --web

# Preconfigure multiple registry / dependency proxy domains during login
glab auth login \
  --hostname gitlab.com \
  --web \
  --container-registry-domains "registry.gitlab.com,gitlab.com"

# Supply every self-managed endpoint so only browser authorization remains interactive
glab auth login --hostname gitlab.example.com --web \
  --api-host gitlab.example.com --ssh-hostname gitlab.example.com \
  --api-protocol https --git-protocol ssh \
  --container-registry-domains registry.gitlab.example.com

# Explicitly opt out of keyring storage (stores the token as plaintext)
glab auth login --hostname gitlab.company.com --insecure-storage \
  --stdin < approved-token-file
認証情報の保存

通常のワークステーションでは、利用可能な場合、glab auth login はデフォルトでオペレーティングシステムのキーチェーンに認証情報を保存します。macOS Keychain、Windows Credential Manager、Linux Secret Service が該当します。キーチェーンへの保存がデフォルトになったため、従来の --use-keyring フラグは非推奨です。ログインを再実行すると、以前設定ファイルに平文で保存されていた認証情報がキーチェーンに移行されます。

平文で設定ファイルに保存することが明示的に必要であり、そのリスクを受け入れる場合に限り、--insecure-storage を使用してください。利用可能なキーチェーンバックエンドがない場合、glab は警告を表示して設定ファイルにフォールバックします。CI（GITLAB_CI または CI が設定されている場合）では、通常キーチェーンを利用できないか、一時的なものであるため、glab はデフォルトで設定ファイルへの保存を使用します。そこにログイン情報を永続化するのではなく、環境変数の認証情報を使用してください。

キーチェーンがロックされている、利用できない、またはアクセスを拒否した場合、glab は認証情報の読み取り失敗をそのまま報告します。結果として生じたエラーを無効なトークンとして扱うのではなく、キーチェーンへのアクセスを修正するか、再認証してください。

glab はトークンを更新する前に、更新された OAuth 認証情報を保存できるかどうかを確認し、複数の glab プロセス間で認証情報の書き込みを直列化します。複数のエージェントやシェルで同じ設定ディレクトリを共有する場合は、分離のためにアクターごとに別の設定ディレクトリを使用することをおすすめします。ただし、glab 自体の外側に追加のファイルロックを設定しないでください。

OAuth アクセストークンは、実質的に期限切れになるまで待つのではなく、5 分間の猶予期間を設けて更新されます。トークンがまだ使用可能で、更新された認証情報を保存できない場合、glab は保存確認を直ちに障害として扱わず、現在のトークンを使い続けます。サブフォルダー配下にあるセルフマネージドインスタンスでは、更新リクエストに設定されたサブフォルダーが使用されます。トークン更新 URL を調査する際は、正確な subfolder ホスト設定を維持してください。

Claude Code などのサンドボックスでは、glab config path --dir が示すディレクトリへの書き込みを glab に許可する必要があります。config.yml ファイルだけでは不十分です。glab は設定ファイルと同じ場所に一時ファイルを書き込み、その後、元のファイルと置き換えます。snap 版をインストールしていて、暗号化された認証情報の保存が必要な場合は、sudo snap connect glab:password-manager-service でキーチェーンへのアクセスを接続してください。接続しない場合、glab auth login は平文での設定ファイル保存にフォールバックできます。

対話形式で再認証する場合、フラグまたはプロンプトで明示的に上書きしない限り、glab はカスタム API ホスト、SSH ホスト、コンテナレジストリドメインなど、ホストごとに保存されている値を維持します。あらかじめ設定を削除するのではなく、再認証後にこれらの値を確認してください。

glab config get api_host --host gitlab.company.com
glab config get ssh_host --host gitlab.company.com
glab config get container_registry_domains --host gitlab.company.com

非対話形式のログインでも、明示的に指定された --git-protocol と --api-protocol の値はホスト設定に保存されます。これは、トークンや標準入力を使うログインなど、プロンプトを必要としないログイン方法にも適用されます。そのため、自動化では後から設定を編集せずに、同じログイン操作でプロトコルを設定できます。利用する前に、結果のホストエントリーを確認してください。

glab auth login --hostname gitlab.company.com --stdin \
  --git-protocol ssh --api-protocol https < approved-token-file
glab config get git_protocol --host gitlab.company.com
glab config get api_protocol --host gitlab.company.com

トークンファイルはバージョン管理の対象外に置き、その内容を表示しないでください。

CI 自動ログイン： GLAB_ENABLE_CI_AUTOLOGIN=true を設定すると、GitLab CI/CD で glab が保存済みのログイン情報なしに CI_JOB_TOKEN を使用できます。GITLAB_TOKEN、GITLAB_ACCESS_TOKEN、OAUTH_TOKEN が設定されている場合は引き続き優先されるため、使用する認証情報が CI_JOB_TOKEN の場合は、これらの変数を設定しないでください。コマンドでプロジェクト、グループ、またはパーソナルアクセストークンが必要な場合は、明示的な環境変数のトークンを使用してください。

エージェントおよび複数アカウントのセットアップ

異なるエージェントを別々の GitLab ユーザーとして表示する必要がある場合は、個別の GitLab ボット／サービスアカウントを使用してください。1 つの GitLab ユーザーに複数の PAT を設定すると、ローテーションやスコープの分離には役立ちますが、表示上の ID を別々にすることはできません。

エージェントが作成者となる GitLab のコメント、返信、承認、その他の書き込みには、Actor identity を使用してください。agent identity は、GitLab の操作が明確にそのエージェント自身の成果物である場合にのみ使用してください。最初に書き込む前に、表示するアクターを決めてください。

運用上は、アクターごとに env ファイルを用意する方法が適しています。

# ~/.config/openclaw/env/gitlab-reviewer.env
GITLAB_TOKEN=glpat-...
GITLAB_HOST=gitlab.com

これらの env ファイルはバージョン管理の対象外にし、アクセス権を制限してください（例：chmod 600）。バックアップから漏えいする可能性にも注意し、最小権限のボット／サービスアカウントトークンを優先してください。再利用しているシェルでは、古い GitLab 認証用変数を先にクリアするか、新しいシェルを起動してください。

ファイルに通常の KEY=value の行が記述されている場合は、glab の実行前に、変数をエクスポートして読み込んでください。

unset GITLAB_TOKEN GITLAB_ACCESS_TOKEN OAUTH_TOKEN GITLAB_HOST
set -a
source ~/.config/openclaw/env/gitlab-<actor>.env
set +a

これが重要な理由：

  • 通常の source では、子プロセスに変数が必ずしもエクスポートされません
  • glab が認識するのは、エクスポートされた環境変数のみです
  • glab が環境変数のトークンを認識できない場合、アクティブなグローバル設定ファイルに保存された共有認証情報へ、気付かないままフォールバックすることがあります
  • 同じシェル／セッションで別の env ファイルを先に読み込んでいると、意図的に切り替えて確認しない限り、書き込み時に危険な形で ID が引き継がれることがあります

こうしたフォールバックや共有認証の動作は、人が使う場合には便利ですが、複数エージェントの自動化では、誤った GitLab アカウントからコメントを投稿したり、MR を作成したり、作業を承認したりする原因になることがあります。

GitLab への書き込み前に必ず行う確認

glab mr note、レビューの送信や承認、スレッドへの返信、および glab api による POST／PATCH／PUT／DELETE 呼び出しなど、GitLab への書き込みの直前に必ず次を実行してください。

glab auth status --hostname "$GITLAB_HOST"
glab api --hostname "$GITLAB_HOST" user

これは、対象アクターの env ファイルで、変更する GitLab インスタンスの正確なホストが GITLAB_HOST に設定されていることを前提としています。両方のコマンドで、そのホスト上に意図した表示アクターが明確に示されるまでは、書き込まないでください。

誤った ID で書き込んだ場合の対処

コメントまたは返信を誤った ID で投稿した場合：

  1. 投稿を停止します。
  2. 必要に応じて、誤ったコメントまたは返信を削除します。
  3. unset GITLAB_TOKEN GITLAB_ACCESS_TOKEN OAUTH_TOKEN GITLAB_HOST を実行するか、新しいシェルを起動します。
  4. set -a; source ...; set +a を使って、正しい env ファイルを読み込みます。
  5. glab auth status --hostname "$GITLAB_HOST" と glab api --hostname "$GITLAB_HOST" user を再実行します。
  6. 正しいアクターで再投稿します。
  7. 差し替えたメッセージの表示上の作成者が誤ったユーザーのままになっていないことをスレッドで確認します。

誤った ID での書き込みによって、コメントや返信以外の状態も変更された場合は、上記のとおり再認証したうえで、正しいアクターとホストを使い、該当する GitLab の取り消し操作を行ってください。たとえば、MR の承認を取り消すか、変更された正確なリソースに対して、補正用の glab api --hostname "$GITLAB_HOST" 更新処理を実行します。

アカウント／インスタンスの切り替え

  1. 現在のアカウントからログアウトする：

    glab auth logout

  2. 新しいインスタンスにログインする：

    glab auth login --hostname gitlab.company.com

  3. 確認する：

    glab auth status --hostname gitlab.company.com
Docker レジストリへのアクセス

  1. Docker ヘルパーを設定します：

    glab auth configure-docker

  2. Docker で認証できることを確認します：

    docker login registry.gitlab.com

  3. プライベートイメージをプルします：

    docker pull registry.gitlab.com/group/project/image:tag

configure-docker は、設定された GitLab レジストリドメインに対してのみ glab を追加します。 関連のない Docker 認証情報ヘルパーはそのまま保持し、同じドメインに別のヘルパーがすでに割り当てられている場合は置き換えません。docker login による従来の認証情報がドメインに残っている場合、glab はヘルパーが優先されることを警告します。ヘルパーによるアクセスを確認した後、影響を受けるエントリーを削除するには、提案された docker logout <domain> コマンドをそのまま実行してください。手動で競合を修復する前に、$DOCKER_CONFIG/config.json をバックアップして内容を確認してください。

通常、glab はヘルパースクリプトを glab バイナリと同じディレクトリにインストールします。そのディレクトリに書き込めない場合は、まず ~/.local/bin に、次に PATH 上にすでに存在する書き込み可能な別のディレクトリにインストールします。選択されたディレクトリが PATH 上にない場合は、Docker をテストする前に、表示されたパスに関する案内に従ってください。ヘルパーを配置するためだけに、glab のインストールディレクトリを広く書き込み可能にしないでください。

トラブルシューティング

「401 Unauthorized」エラー：

  • ステータスを確認します：glab auth status
  • トークンの有効期限が切れていないことを確認します（GitLab の設定を確認してください）
  • 再認証します：glab auth login

認証方法を変更した後も、再ログインしても解決しない場合：

  • ブラウザー／OAuth ログインからトークンベースのログインに切り替えた後も、glab が古い保存済み認証情報を使用しているように見える場合は、設定を手動で編集する必要があると決めつけず、もう一度 glab auth login を実行してください。
  • 再ログイン後、失敗したコマンドを再試行する前に glab auth status で確認してください。

環境変数トークンによる認証の失敗：

  • GITLAB_TOKEN、GITLAB_ACCESS_TOKEN、または OAUTH_TOKEN がエクスポートされている場合、保存済みの認証情報より優先されます。
  • GITLAB_TOKEN と GITLAB_ACCESS_TOKEN は、保存済みの OAuth プロファイルとは別にパーソナルアクセストークンとして扱われます。そのため、一時的な PAT は保存済みの OAuth 状態を引き継いだり、更新したりしません。
  • ホストが OAuth 用に設定されている一方で、環境変数に OAuth アクセストークンが含まれている場合は、GLAB_IS_OAUTH2=true を設定してください。そうしないと、glab は環境変数のトークンをパーソナルアクセストークンとして送信します。401 の後、glab auth status はこの方式の不一致を報告します。
  • 認証が突然失敗した場合、保存済みのログインが壊れていると決めつける前に、環境変数のトークンが使用されていないか確認してください。この優先順位が適用される場合、glab auth login と glab auth status は警告を表示します。
  • type glab を実行し、トークンを意図的に注入するラッパー（たとえば、1Password のシェルプラグインのエイリアス）と、通常の実行ファイルパスを区別してください。ラッパーは想定どおりで、対応が不要な場合があります。通常のパスの場合、トークンはシェルプロファイル、現在の環境、または CI 変数に由来します。
  • こうした認証失敗は、書き込み前の確認だけでなく、読み取り操作と書き込み操作の両方に影響することがあります。
  • GitLab への書き込みを行う前に、glab auth status と glab api user で有効なユーザーとトークンの取得元を確認してください。
  • 複数のエージェントが動作するシェルでは、再試行する前に set -a; source ...; set +a を使って、意図した環境ファイルを明示的に再読み込みしてください。

セルフマネージド環境での OAuth URL または更新の問題：

  • 設定済みのホスト／サブフォルダー全体を指定して再認証してください。ブラウザー OAuth では、認証 URL に設定済みのサブフォルダーが含まれます。
  • OAuth トークンの更新でも、設定済みのサブフォルダーが使われます。トークンエンドポイントがホストのルートにあると決めつける前に、glab config get subfolder --host <host> で確認してください。
  • 有効期限まで5分以内の保存済み OAuth トークンは、認証情報を保存できる場合、事前に更新されます。
  • 再認証の応答に新しいリフレッシュトークンが含まれていない場合、既存のリフレッシュトークンは消去されず、そのまま保持されます。
  • 更新が invalid_grant で失敗した場合は、glab auth login を再実行してください。OAuth の許可が取り消されている、または有効期限が切れている場合や、以前に認証情報の保存に失敗している場合、保存済みの OAuth 認証情報が古いままになっていることがあります。
  • サンドボックス内で認証情報の保存エラーにより OAuth の更新が失敗した場合は、glab config path --dir への書き込みアクセスを許可してから再認証してください。同じ古いトークンで再試行しても、通常は保存済みの認証情報は修復されません。
  • Docker やその他のヘルパーは、パーソナルアクセストークンで認証されたホストでは OAuth の更新をスキップします。OAuth の状態を調査する前に、トークンの種類を確認してください。

複数のインスタンス：

  • --hostname フラグを使用してインスタンスを指定します
  • インスタンスごとに個別の認証情報が保持されます

Docker の認証に失敗する場合：

  • 再実行します：glab auth configure-docker
  • Docker の設定を確認します：cat ~/.docker/config.json
  • ヘルパーが設定されていることを確認します："credHelpers": { "registry.gitlab.com": "glab-cli" }

サブコマンド

フラグの詳細については、references/commands.md を参照してください：

  • login - GitLab インスタンスで認証します
  • logout - GitLab インスタンスからログアウトします
  • status - 認証ステータスを表示します
  • configure-docker - GitLab レジストリを使用するよう Docker を設定します
  • docker-helper - Docker 認証情報ヘルパー
  • dpop-gen - DPoP トークンを生成します

関連スキル

初期設定：

  • 認証後、CLI のデフォルトを設定するには glab-config を参照してください
  • SSH キーの管理については glab-ssh-key を参照してください
  • コミット署名の設定については glab-gpg-key を参照してください

リポジトリの操作：

  • リポジトリのクローンについては glab-repo を参照してください
  • 初めてクローン／プッシュする前に認証が必要です

コメント

Markdown 対応