GLab CLI その2 - GLab CLI 実践チュートリアル集

ターミナルから GitLab を操る喜び - GLab CLI で開発体験が変わる

開発者の皆さんは、毎日どのくらいの時間をブラウザとターミナルの間で行き来していますか？ GitLab の Web UI で merge request を確認して、ターミナルに戻ってコマンドを実行する。その繰り返しは、実は大きな時間ロスになっています。

そこに登場するのが GLab です。GitLab の公式 CLI ツールである GLab は、皆さんが既に使い慣れた git コマンドの隣で、GitLab のすべての機能をターミナルから直接操作できます。ウィンドウを切り替える必要はもうありません。

1. GLab とは何か

GLab は、GitLab.com、GitLab Dedicated、GitLab Self-Managed のすべてのインスタンスで動作するオープンソースの CLI ツールです。単なる issue や merge request の管理ツールではなく、CI/CD パイプラインの実行、リリース管理、Kubernetes エージェントの操作まで、GitLab の主要な機能をすべてターミナルから操作できます。

1.1 何ができるのか

GLab で実現できることは、想像以上に広がっています。

CI/CD パイプラインの管理: パイプラインの状態確認、ジョブの再実行、ログの確認をすべてターミナルから実行できます。
Merge Request と Issue の操作: リストの表示、作成、承認、マージまで、Web UI と同じ操作がコマンドラインで可能です。
リリース管理: チェンジログの生成、リリースの作成と管理を自動化できます。
GitLab Duo との連携: AI を活用した glab duo ask コマンドで、Git コマンドについての質問に答えてもらえます。
Kubernetes エージェント管理: GitLab agents の設定と管理をターミナルから行えます。

2. 動作環境と要件

GLab は GitLab 16.0 以降の公式サポートを受けています。特定のコマンドはより新しいバージョンが必要な場合もありますが、GitLab 15.x 以前でも多くのコマンドが動作する可能性があります。ただし、これらの古いバージョンに対するサポートは提供されていません。

複数の認証済み GitLab インスタンスに対応しており、Git リポジトリのリモートから認証済みホスト名を自動検出します。

3. インストール方法

GLab の導入は非常にシンプルです。複数のインストール方法が用意されています。

3.1 Homebrew でのインストール

Homebrew は macOS、Linux、Windows (WSL) で公式にサポートされているパッケージマネージャーです。

# インストール
brew install glab

# アップデート
brew upgrade glab

3.2 バイナリのダウンロード

リリースページから、お使いの OS に適したバイナリをダウンロードできます。

3.3 その他のインストール方法

コミュニティによってメンテナンスされている、公式にはサポートされていない他のインストール方法も利用可能です。

3.4 ソースからのビルド

サポートされているバイナリが見つからない場合は、ソースからビルドできます。

3.4.1 ビルドの前提条件

make
Go 1.22 以上

3.4.2 ソースからのビルド手順

go version コマンドを実行して、Go 1.22 以上がインストールされていることを確認します。Go がインストールされていない場合は、Go の公式ウェブサイトの指示に従ってインストールしてください。
以下のコマンドを実行して、glab を $GOPATH/bin にインストールします。

go install gitlab.com/gitlab-org/cli/cmd/glab@main

GLab のソースコードは $GOPATH/src/gitlab.com/gitlab-org/cli に配置されます。
$GOPATH/bin または $GOBIN が $PATH に含まれていない場合は、以下のコマンドを実行して PATH を更新します。

export PATH=$PWD/bin:$PATH

glab version コマンドを実行して、インストールが成功したことを確認します。

4. 認証方法

GLab を使用する前に、GitLab インスタンスに対して認証する必要があります。glab auth login をインタラクティブに実行すると、Git リポジトリから GitLab インスタンスを自動検出し、オプションとして表示されます。これにより、ホスト名を手動で入力する手間が省けます。

4.1 OAuth (GitLab.com)

GitLab.com に接続された OAuth アプリケーションで GLab をインストールして認証するには、以下の手順に従います。

glab auth login でインタラクティブセットアップを開始します。
サインインする GitLab インスタンスとして GitLab.com を選択します。
ログイン方法として Web を選択します。これにより、Web ブラウザが起動し、GitLab CLI が GitLab.com アカウントを使用することを許可するよう要求されます。
Authorize を選択します。
ターミナルで認証プロセスを完了し、ニーズに応じて適切なオプションを選択します。

4.2 OAuth (GitLab Self-Managed、GitLab Dedicated)

前提条件として、ユーザー、グループ、またはインスタンスレベルで OAuth アプリケーションを作成し、そのアプリケーション ID を取得しておく必要があります。OAuth アプリケーションは以下のパラメータで設定する必要があります。

Redirect URI: http://localhost:7171/auth/redirect
Confidential: 選択しない
Scopes: openid、profile、read_user、write_repository、api

認証手順は以下の通りです。

以下のコマンドでアプリケーション ID を保存します。<CLIENT_ID> にはアプリケーション ID を、<HOSTNAME> にはホスト名を指定します。

glab config set client_id <CLIENT_ID> --host <HOSTNAME>

glab auth login --hostname <HOSTNAME> でインタラクティブセットアップを開始します。
ログイン方法として Web を選択します。これにより、Web ブラウザが起動し、GitLab CLI が GitLab Self-Managed または GitLab Dedicated アカウントを使用することを許可するよう要求されます。
Authorize を選択します。
ターミナルで認証プロセスを完了し、ニーズに応じて適切なオプションを選択します。

4.3 パーソナルアクセストークン

パーソナルアクセストークンで GLab をインストールして認証するには、以下の手順に従います。

少なくとも api と write_repository スコープを持つ GitLab パーソナルアクセストークンを取得します。
- GitLab.com の場合は、パーソナルアクセストークンページで作成します。
- GitLab Self-Managed と GitLab Dedicated の場合は、https://gitlab.example.com/-/user_settings/personal_access_tokens?scopes=api,write_repository にアクセスします。gitlab.example.com をインスタンスのドメイン名に置き換えてください。
glab auth login でインタラクティブセットアップを開始します。
GitLab インスタンスに応じて、以下の方法で認証します。
- GitLab SaaS の場合: ファイルからトークンを読み込んで gitlab.com に対して認証します。
```
glab auth login --stdin < myaccesstoken.txt
```
- GitLab Self-Managed と GitLab Dedicated の場合: ファイルから読み込んで認証します。
```
glab auth login --hostname gitlab.example.com --stdin < myaccesstoken.txt
```
これにより、Git リポジトリ内でインスタンスのホストと一致するリモートがある場合、認証済みの glab コマンドを実行できます。または、GITLAB_HOST を設定してインスタンスにコマンドを向けることもできます。
- トークンとホスト名で認証 (共有環境では非推奨):
```
glab auth login --hostname gitlab.example.org --token xxxxx
```
認証情報はグローバル設定ファイルに保存されます。

4.4 CI ジョブトークン

CI ジョブトークンで GLab をインストールして認証するには、glab コマンドを GitLab CI ジョブ内で実行する必要があります。トークンは GitLab Runner によって CI_JOB_TOKEN 環境変数を通じて自動的に提供されます。

CI ジョブトークンの使用を許可するエンドポイントは GitLab ドキュメントに記載されています。

4.4.1 自動ログイン (実験的機能)

GLAB_ENABLE_CI_AUTOLOGIN 変数を true に設定することで、実験的な CI 自動ログイン機能を有効にできます。この機能は、glab が GitLab CI で実行されているかどうかを自動的に検出し、事前定義された CI/CD 変数を使用してサインインします。

GLAB_ENABLE_CI_AUTLOGIN=true glab release list -R $CI_PROJECT_PATH

4.4.2 手動ログイン

glab auth login --job-token $CI_JOB_TOKEN --hostname $CI_SERVER_HOST --api-protocol $CI_SERVER_PROTOCOL
GITLAB_HOST=$CI_SERVER_URL glab release list -R $CI_PROJECT_PATH

5. 設定方法

デフォルトでは、GLab は XDG Base Directory Spec に従い、複数の場所で設定ファイルを検索します。

5.1 設定レベル

GLab は異なるレベルで設定できます。

システム全体 (すべてのユーザー): /etc/xdg/glab-cli/config.yml (または $XDG_CONFIG_DIRS/glab-cli/config.yml) に設定を配置します。Linux ディストリビューションとシステム管理者がデフォルト設定を提供するのに便利です。ユーザー設定はシステム全体の設定をオーバーライドします。
グローバル (ユーザー単位): glab config set --global editor vim を実行します。グローバル設定ファイルは ~/.config/glab-cli/config.yml (または $XDG_CONFIG_HOME/glab-cli/config.yml) にあります。この場所をオーバーライドするには、GLAB_CONFIG_DIR 環境変数を設定します。
現在のリポジトリ: Git リポジトリ内の任意のフォルダで glab config set editor vim を実行します。ローカル設定ファイルは現在の作業 Git ディレクトリの .git/glab-cli/config.yml にあります。
ホスト単位: glab config set editor vim --host gitlab.example.org を実行し、--host パラメータをニーズに応じて変更します。ホスト単位の設定情報は常にグローバル設定ファイルに保存されます。global フラグの有無に関わらず同じです。

5.2 設定検索順序

GLab が設定ファイルを検索する際の順序は以下の通りです (優先度が高い順)。

$GLAB_CONFIG_DIR/config.yml (GLAB_CONFIG_DIR が設定されている場合)
~/.config/glab-cli/config.yml (レガシー場所、後方互換性のため)
$XDG_CONFIG_HOME/glab-cli/config.yml (プラットフォーム固有の XDG 場所)
$XDG_CONFIG_DIRS/glab-cli/config.yml (システム全体の設定、デフォルト: /etc/xdg/glab-cli/config.yml)

最初に見つかった設定ファイルが使用されます。

5.3 設定ファイルの場所

後方互換性のため、GLab はすべてのプラットフォームで ~/.config/glab-cli/config.yml を最初にチェックします。レガシー設定が存在しない場合、GLab はプラットフォーム固有の XDG Base Directory 場所を使用します。

Linux: ~/.config/glab-cli/config.yml (XDG_CONFIG_HOME)
macOS: ~/Library/Application Support/glab-cli/config.yml (XDG_CONFIG_HOME)
Windows: %APPDATA%\glab-cli\config.yml (XDG_CONFIG_HOME)

5.4 GitLab Self-Managed または GitLab Dedicated インスタンスの設定

Git リポジトリの外にいるとき、GLab はデフォルトで gitlab.com を使用します。Git リポジトリ内にいないときに GLab がデフォルトで GitLab Self-Managed または GitLab Dedicated インスタンスを使用するようにするには、ホスト設定を変更します。以下のコマンドを使用し、gitlab.example.com をインスタンスのドメイン名に置き換えます。

glab config set -g host gitlab.example.com

この設定により、Git リポジトリの外でコマンドを実行しながら GitLab Self-Managed または GitLab Dedicated インスタンスを使用できます。例えば、以下のようなコマンドが実行できます。

glab repo clone group/project
glab issue list -R group/project

デフォルトのドメイン名を設定しない場合は、現在のコマンドに対して GITLAB_HOST 環境変数で指定できます。

GITLAB_HOST=gitlab.example.com glab repo clone group/project
GITLAB_HOST=gitlab.example.com glab issue list -R group/project

Git リポジトリ内にいるとき、GLab はそのリポジトリの GitLab ホストをデフォルトで使用します。例えば、glab issue list は現在のディレクトリの Git リポジトリのすべての issue をリストします。

5.5 mTLS 証明書の設定

相互 TLS (Mutual Transport Layer Security) 証明書を GLab で使用するには、グローバル設定ファイル (~/.config/glab-cli/config.yml) を編集して接続情報を提供します。

hosts:
    git.your-domain.com:
        api_protocol: https
        api_host: git.your-domain.com
        token: xxxxxxxxxxxxxxxxxxxxxxxxx
        client_cert: /path/to/client.crt
        client_key: /path/to/client.key
        ca_cert: /path/to/ca-chain.pem

ca_cert は、公開署名されたサーバー証明書を使用する場合、mTLS サポートではオプションです。
token は別の認証方法を使用する場合は不要です。

5.6 自己署名証明書の設定

GitLab Self-Managed と GitLab Dedicated インスタンスで自己署名証明書をサポートするように GitLab CLI を設定するには、以下のいずれかを実行します。

TLS 検証を無効にする場合:

glab config set skip_tls_verify true --host gitlab.example.com

自己署名 CA へのパスを追加する場合:

glab config set ca_cert /path/to/server.pem --host gitlab.example.com

6. 実際に使ってみる - コマンドの例

GLab の真価は、実際に使ってみるとわかります。以下は、日常的に使えるコマンドの例です。

6.1 Merge Request の操作

# 自分に割り当てられた MR をリスト表示
glab mr list --assignee=@me

# レビューをリクエストされた MR を表示
glab mr list --reviewer=@me

# MR を承認
glab mr approve 235

# MR の詳細を表示
glab mr view 235

6.2 Issue の管理

# マイルストーン、タイトル、ラベルを指定して Issue を作成
glab issue create -m release-2.0.0 -t "My title here" --label important

# 自分に割り当てられた Issue をリスト表示
glab issue list --assignee=@me

6.3 CI/CD パイプラインの確認

# 最新のパイプラインを表示
glab ci view

# パイプラインのジョブをリスト表示
glab job list

# ジョブのログを表示
glab job trace <job-id>

# 失敗したジョブを再実行
glab job retry <job-id>

6.4 API への直接アクセス

# GitLab API に認証済みリクエストを送信
glab api projects/:id/issues

6.5 コマンドの基本パターン

GLab のコマンドは以下のパターンに従います。

glab <command> <subcommand> [flags]

多くのコアコマンドにはサブコマンドがあります。複雑な操作も直感的に実行できます。

7. 豊富なコマンド群 - 30 以上のコマンドで GitLab を完全制御

GLab には、30 以上のコマンドが用意されています。主要なものを紹介します。

glab alias          # エイリアスの作成・管理
glab api            # GitLab API への直接アクセス
glab auth           # 認証状態の管理
glab changelog      # チェンジログの操作
glab check-update   # CLI の更新確認
glab ci             # CI/CD パイプラインの管理
glab cluster        # Kubernetes エージェントの管理
glab completion     # シェル補完スクリプトの生成
glab config         # CLI 設定の設定と取得
glab deploy-key     # デプロイキーの管理
glab duo            # GitLab Duo AI 機能の利用
glab gpg-key        # GPG キーの管理
glab incident       # インシデント管理
glab issue          # Issue の操作
glab iteration      # イテレーション情報の取得
glab job            # CI/CD ジョブの管理
glab label          # ラベルの管理
glab mcp            # Model Context Protocol (MCP) サーバーの操作 (実験的)
glab milestone      # グループまたはプロジェクトマイルストーンの管理
glab mr             # Merge Request の操作
glab opentofu       # OpenTofu または Terraform 統合の操作
glab release        # リリースの管理
glab repo           # GitLab リポジトリとプロジェクトの操作
glab schedule       # CI/CD スケジュールの操作
glab securefile     # プロジェクトのセキュアファイルの管理
glab snippet        # スニペットの作成・表示・管理
glab ssh-key        # SSH キーの管理
glab stack          # スタックされた diff の作成・管理・操作
glab token          # パーソナル、プロジェクト、グループトークンの管理
glab user           # GitLab ユーザーアカウントとの相互作用
glab variable       # GitLab プロジェクトまたはグループの変数管理
glab version        # CLI のバージョン情報表示

各コマンドは、さらに細かいサブコマンドを持っており、複雑な操作も直感的に実行できます。

8. GitLab Duo との連携 - AI の力を借りる

GLab には、GitLab Duo AI/ML 機能との連携も組み込まれています。glab duo ask コマンドを使えば、Git コマンドについての質問に AI が答えてくれます。

glab duo ask "How do I rebase my branch?"

忘れてしまった Git コマンドの使い方や、複雑な操作方法を素早く思い出せます。

9. 環境変数による細かい制御

GLab は、環境変数による設定も充実しています。主要な環境変数を紹介します。

9.1 GitLab アクセス変数

環境変数	説明
`GITLAB_TOKEN`	API リクエスト用の認証トークン
`GITLAB_HOST`	デフォルトの GitLab ホスト (デフォルト: `https://gitlab.com`)
`GITLAB_API_HOST`	API エンドポイントが見つかるホスト
`GITLAB_CLIENT_ID`	GitLab OAuth 2.0 アプリケーションのクライアント ID
`GITLAB_GROUP`	デフォルトの GitLab グループ
`GITLAB_REPO`	デフォルトの GitLab リポジトリ

9.2 GLab 設定変数

環境変数	説明
`GLAB_CONFIG_DIR`	設定ファイルのディレクトリ (デフォルト: `~/.config/glab-cli/`)
`GLAB_DEBUG_HTTP`	HTTP トランスポート情報の出力 (デフォルト: `false`)
`GLAB_SEND_TELEMETRY`	テレメトリデータの送信制御 (デフォルト: `true`)
`NO_PROMPT`	プロンプトの無効化 (デフォルト: `false`)
`DEBUG`	詳細ログ情報の出力 (デフォルト: `false`)

9.3 トークンと環境変数の優先度

GLab はトークンを以下の順序で使用します。

環境変数 (GITLAB_TOKEN)
設定ファイル ($HOME/.config/glab-cli/config.yml)

10. CI/CD パイプラインでの活用

GLab の真の価値は、CI/CD パイプラインの中で発揮されます。例えば、パイプラインの中から別のプロジェクトの Issue を作成したり、リリースを自動生成したりできます。

# CI ジョブトークンを使った自動ログイン
GLAB_ENABLE_CI_AUTLOGIN=true glab release list -R $CI_PROJECT_PATH

または、手動でトークンを指定することもできます。

glab auth login --job-token $CI_JOB_TOKEN --hostname $CI_SERVER_HOST --api-protocol $CI_SERVER_PROTOCOL
GITLAB_HOST=$CI_SERVER_URL glab release list -R $CI_PROJECT_PATH

11. 互換性と安定性 - 信頼できるツール

GLab は GitLab 16.0 以降の公式サポートを受けており、セマンティックバージョニング (SemVer) に従っています。

11.1 バージョン変更の分類

MAJOR バージョン: コマンドの削除、動作の変更、または新しい必須フラグの追加が行われた場合。
MINOR バージョン: 新しいコマンドまたは オプション フラグが追加された場合。
PATCH バージョン: バグが修正された場合。

11.2 互換性

破壊的な変更は MAJOR バージョンでのみ導入されるよう最善を尽くしています。セキュリティ問題や重大なバグ修正の場合を除き、安定性が保証されています。実験的な機能は明確にマークされており、安定版の機能に影響を与えません。

12. コミュニティと貢献

GLab はオープンソースプロジェクトであり、コミュニティからの貢献を歓迎しています。GitHub CLI や lab など、他の優れた CLI ツールからインスピレーションを受けながら、GitLab 独自の機能を追加し続けています。

Lab は CI/CD コマンド (ci view や ci trace など) の多くの基盤となっています。

バグ報告や機能リクエストは、issue tracker で行えます。

詳しくはこちら

13. まとめ - ターミナルから GitLab の全力を引き出す

GLab は、単なる便利なツールではなく、開発ワークフローを根本的に変えるポテンシャルを持っています。ブラウザとターミナルの間を行き来する時間を削減し、その分を実際のコード作成に充てることができます。

複数の GitLab インスタンスに対応し、柔軟な設定が可能で、CI/CD パイプラインとの統合も深い。さらに、GitLab Duo との連携により、AI の力も活用できます。

30 以上のコマンドで GitLab のほぼすべての機能をターミナルから操作でき、セマンティックバージョニングに従った安定性も保証されています。

今こそ、GLab を試してみる時です。ターミナルから GitLab を完全に操る喜びを、ぜひ体験してください。

brew install glab
glab auth login
glab mr list --assignee=@me

この 3 行から、皆さんの開発体験は変わり始めます。