GitPowershellWindows

GitlabAPI経由でグループ+メンバー一覧をPowershellで取得する

Git

オンプレ環境でソースコード管理「Gitllab」を利用している方は多くいるかと思います。

Gitlabの管理画面にrootユーザーでログオンすればグループやメンバを表示することはできますが、リストとしての一括取得はできません。

そのため、グループやユーザーの棚卸しなどをしたいと思った際には、いちいち管理画面からコピペするのは手間がかかってしまいます。

今回はGitlabに登録されているグループとメンバーの一覧を取得するPowershellスクリプトを作成します。

Gitlabグループやメンバー一覧を取得する方法として、Gitlab APIの機能を利用します。

試した環境

  • Windows10 Pro バージョン1909
  • CPU:Intel Core i7-2600K
  • メモリ:24GB
  • ディスク:240GB (SSD)

事前準備

Gitlab API Tokenの取得

Gitlab APIはデフォルトで有効になっている機能ですが、利用するにはあらかじめGitlabにアクセスための認証情報である「Access Tokens」を取得する必要があります。

Gitlab APIのURLへアクセスする際にこの「Access Tokens」を添えることでGitlab APIを利用することができます。

Gitlabにログオンして[UserSetting]->[Access Tocken]で作成します。必要な権限にチェックしてから作成します。

[Create personal access token]をクリックするとTokenが表示されます。

この文字列がGitlabAPIの認証に使われるTokenになりますのでメモしておいてください。

また、当然ですがTokenについてはパスワードと同じレベルで取り扱うようにしてください。

PowerShellの有効化

Windows10のデフォルトではPowerShellがポリシーで利用できないように制御されてますので、ポリシーを変更します。

PowerShellコンソールを管理者として起動して以下のコマンドを打ち込みます。

PS C:\WINDOWS\system32> Set-ExecutionPolicy RemoteSigned

実行ポリシーの変更
実行ポリシーは、信頼されていないスクリプトからの保護に役立ちます。実行ポリシーを変更すると、about_Execution_Policies
のヘルプ トピック (https://go.microsoft.com/fwlink/?LinkID=135170)
で説明されているセキュリティ上の危険にさらされる可能性があります。実行ポリシーを変更しますか?
[Y] はい(Y)  [A] すべて続行(A)  [N] いいえ(N)  [L] すべて無視(L)  [S] 中断(S)  [?] ヘルプ (既定値は "N"): y

テストするGitlabの環境について

テスト対象としているGitlab環境については以下となります。

  • サーバ名:gitlab.syachiku.local
  • 登録されているグループ:2つ(Group1/Group2)
  • 登録されているユーザ:10ユーザ(User1,User2・・・User10)

PowerShellスクリプトの作成

Gitlab APIでグループとメンバーの一覧を取得するURL

まずアクセスすべきGitlab APIのURLについて説明します。

グループ取得URL

Groupを取得するURLは「https://gitlab.syachiku.local/api/v4/groups」になります。
WEBページへアクセスするとGroup一覧を含んだjsonファイルが表示されます。

メンバー取得URL

Groupメンバーを取得するURLは「https://gitlab.syachiku.local/api/v4/groups/<group_id>/members」になります。

<group_id>にはグループのidが入ります。上でグループを取得した際にGroup1のidが「44」であることが分かりますのでアクセスするとGroup1のメンバー一覧が表示されます。

Gitlab APIではグル-プやメンバー以外にもプロジェクトやユーザーなどの取得もできます。詳細はGitlabの公式ドキュメントを参照してください。

Extend with GitLab | GitLab
GitLab product documentation.

PowerShellスクリプトでGitLab APIへアクセスする方法

GitLabAPIへのアクセスにはPowershellの「Invoke-RestMethod」コマンドを利用します。

例として以下のスクリプトを作りました。URLやTOKENを変えれば使えると思います。

実行すると実行フォルダにgitlab.csvというグループとメンバー一覧を含んだCSVファイルが作成されます。

$URL_BASE = 'https://gitlab.syachiku.local/api/v4/groups'
$TOKENS = 'jLoyJioqJvwQc8E5Nwd6'
$RESULT_CSV = 'gitlab.csv'

# 自己証明書のサイトの場合に、証明書を無視する設定
add-type @"
    using System.Net;
    using System.Security.Cryptography.X509Certificates;
    public class TrustAllCertsPolicy : ICertificatePolicy {
        public bool CheckValidationResult(
            ServicePoint srvPoint, X509Certificate certificate,
            WebRequest request, int certificateProblem) {
            return true;
        }
    }
"@
[System.Net.ServicePointManager]::CertificatePolicy = New-Object TrustAllCertsPolicy


# Groupを取得
$URL_GROUPS = $URL_BASE+'?private_token='+$TOKENS
$gitlabGroups = @()
$gitlabGroups = Invoke-RestMethod -Method get -Uri $URL_GROUPS

# Memberを取得
foreach ($gitlabGroup in $gitlabGroups) {
    $URL_MEMBERS = $URL_BASE+'/'+$gitlabGroup.id+'/members?private_token='+$TOKENS
    $gitlabMembers = Invoke-RestMethod -Method get -Uri $URL_MEMBERS
    $gitlabMembers | Add-Member -MemberType NoteProperty -Name 'group_name' -Value $gitlabGroup.name
    # CSVファイルに追記
    $gitlabMembers | Select-object "group_name", "name","username","state", "access_level" | Export-Csv -Path $RESULT_CSV -Encoding Default -Append -NoTypeInformation
}
"group_name","name","username","state","access_level"
"Group1","Administrator","root","active","50"
"Group1","user1","user1","active","40"
"Group1","user2","user2","active","30"
"Group1","user3","user3","active","30"
"Group1","user4","user4","active","30"
"Group1","user5","user5","active","30"
"Group1","user6","user6","active","30"
"Group1","user7","user7","active","30"
"Group1","user8","user8","active","30"
"Group1","user9","user9","active","30"
"Group1","user10","user10","active","30"
"Group2","Administrator","root","active","50"
"Group2","user2","user2","active","40"
"Group2","user3","user3","active","30"
"Group2","user1","user1","active","30"

簡単に解説します。

まず、Gitlab APIへアクセスする際に、gitlabサーバがSSLサイトに自己証明書を使っている場合に、Invoke-RestMethodでエラーになるので無視する設定を追加しています。

その後、GitlabAPI経由グループ一覧を取得して、そのグループのIDを元にメンバー一覧を取得してます。

最後にMember一覧のオブジェクトにグループ名を追加してCSVに書き出ししています。

access_levelは40がMintainer、30がDeveloperの権限です。

※結構適当な感じで済ませてしまってますが、必要であればきちんと整形しながら取得してください

グループやメンバーが多くなった場合の対応

GitlabのAPI経由では1回のアクセスで取得できるグループやメンバーの数はデフォルトでは「20」までです。

「per_page」のパラメータをつけることで最大100まで取得することができますが、100以上のグループやメンバー数になった場合には「page」パラメータで2ページ目、3ページ目と取得する必要があります。

グループの部分だけですが、スクリプトの例としてはこんな感じでしょうか。


# Page変数を使う
$page=1

# Groupを取得するURL(ページ指定あり)
$URL_GROUPS = $URL_BASE+'?private_token='+$TOKENS+'&page='+$page

$resultGroups = @()
:label01 while($true){
  $gitlabGroups = @()
  $gitlabGroups = Invoke-RestMethod -Method get -Uri $URL_GROUPS

  # 必要な項目を取得->resultGroupに追加
  foreach($gitlabGroup in $gitlabGroups){
    $resultGroups += @{ "group_name" = $gitlabGroups.name }
  }

  # もし20以上のグループであれば再度取得
  if(gitlabGroups.count -eq '20'){
    $page ++
    continue label01
  }
  break
}

まず、pageを1にセットして、取得したグループ数が20以上であれば2ページ目を取得、そうでなければ終了という感じです。foreachでループして必要な値を$resultGroupsの配列に追加していってます。

他にもRedmineなどのAPIを利用できるシステムでもページをめくって取得する必要がありますのでこのやり方を応用することができます。

まとめ

今回はGitlab APIへPowerShellスクリプトでアクセスして、グループとメンバー一覧を取得するスクリプトについて作成しました。

Gitlabのプロジェクトやユーザ等の一覧についても同様に取得することができますし、他のAPIを利用しているシステムにも応用できると思いますので、ぜひ参考にしていただければと思います。

今回は以上となります。

コメント