はじめに
GitLabでユーザーの棚卸しや監査を行う際、登録されているユーザーの一覧をCSV形式で出力したい場面があります。
GitLabのWeb UIからもユーザー一覧を確認できますが、CSV形式で出力したい場合はREST APIを利用すると簡単にエクスポートできます。
（台帳に転記する際などに便利です。）
今回は、GitLab APIを使用してユーザー一覧をCSV出力する方法をまとめます。
想定環境・前提条件は次の通りです。
- 想定環境
- Self Host GitLab
- GitLab Community EditionのLinux Package(Omnibus)
- v18.1.0 / v18.9.1で確認済み
- Self Host GitLab
- 前提条件
- GitLabの管理者権限を持つユーザーであること
-
curl、jqコマンドが利用可能
手順
Personal Access Tokenを発行する
最初にAPI実行用のPersonal Access Tokenを発行します。
- Web UI右上のユーザーアイコンから Preferences を開く
- 左ペインの Access Tokens を選択する
- 次の内容でTokenを発行する
項目 設定値 Token name 任意 Expiration date 任意（短期間を推奨） Scopes api（またはread_api）およびadmin_mode - Create personal access token をクリックする
- 表示されたTokenを手元にコピーする
注意
Tokenは発行時しか表示されないため、手元にコピーしておきます。
APIを実行する
環境変数にTokenとGitLabのURLを設定します。
export TOKEN="<作成したToken>"
export GITLAB_URL="https://example.com"
続いて、次のコマンドを実行します。
echo "name,email,state,created_at,last_sign_in_at" > gitlab_account_list.csv
curl -s --header "PRIVATE-TOKEN: ${TOKEN}" \
"${GITLAB_URL}/api/v4/users?per_page=100" \
| jq -r '
.[] |
select(.state == "active" or .state == "deactivated") |
[
.name,
.email,
.state,
.created_at,
.last_sign_in_at
] | @csv' \
>> gitlab_account_list.csv
実行後、カレントディレクトリにgitlab_account_list.csvが作成されます。
出力されたCSVには、次の情報が含まれます。
| 項目 | 内容 |
|---|---|
| name | ユーザー名 |
| メールアドレス | |
| state | ユーザー状態 |
| created_at | 作成日時 |
| last_sign_in_at | 最終ログイン日時 |
補足1
/api/v4/usersで取得可能なパラメータは他にも存在します。
今回はユーザー棚卸しを目的としているため、上記項目のみをjqで抽出しています。
補足2
ユーザー状態についてはこちらを参照してください。
今回は"active"と"deactivated"のユーザーのみを抽出しています。
他の状態のユーザー（blockedやbannedなど）も併せて抽出したい場合は、select(.state == "active" or .state == "deactivated") |の行を削除してください。
補足
100ユーザーを超える場合
GitLab APIではPagination（ページネーション）の仕組みにより、一度に取得できる件数が制限されています。
デフォルトでは20件ですが、per_pageを指定することで最大100件まで取得できます。
/api/v4/users?per_page=100
100件を超える場合は、pageパラメータを指定して複数回に分けて取得します。
例えばユーザー数が200人の場合、次のようになります。
1～100件目
curl -s --header "PRIVATE-TOKEN: ${TOKEN}" \
"${GITLAB_URL}/api/v4/users?per_page=100&page=1"
101～200件目
curl -s --header "PRIVATE-TOKEN: ${TOKEN}" \
"${GITLAB_URL}/api/v4/users?per_page=100&page=2"
必要に応じて取得したCSVを結合することで、全ユーザーを一覧として取得できます。
補足1
本記事では紹介しませんが、レスポンスヘッダーの
X-Next-Pageを利用することで、最後のページまで自動取得するスクリプトを作成することもできます。
まとめ
GitLab APIを利用すると、ユーザー一覧をCSV形式で簡単に取得できます。
特にユーザー棚卸しや監査対応では、CSVとして出力できるとExcelなどで加工しやすいため便利です。
ユーザー数が100件を超える環境では、Paginationを利用して複数回取得する点だけ注意すれば、特別なツールを用意しなくても、手軽にユーザー一覧を取得できます。