エンジニアの皆さん、こんにちは。現場で泥臭い自動化を積み重ねてきた先輩エンジニアとして、今日は皆さんに「GitLabを真に支配する力」を授けたいと思います。
GitLabを使いこなす中で、「数百のリポジトリを横断して進捗を見たい」「特定のラベルがついたイシューだけを抽出してレポートしたい」といった要求にぶつかったことはありませんか？ REST APIでこれをやろうとすると、N+1問題でリクエストが洪水になり、タイムアウトに泣くことになります。
そこで登場するのが GitLab GraphQL API です。今日は、これを使いこなして「面倒な手作業」を「秒殺の自動化」に変える極意を伝授します。
—
1. なぜGraphQLなのか？：RESTからの解放
REST APIは、階層的なデータを取得する際に「プロジェクトを取得→イシューを取得→ラベルを取得」と何度も往復が必要です。
対してGraphQLは、「必要なデータを、必要な分だけ、一度の通信で」取得できます。数百のリポジトリを扱うなら、GraphQL一択です。
2. 最初のステップ：環境構築と認証
特別なインストールは不要です。GitLabが動いているなら既に準備は整っています。必要なのは「Personal Access Token」だけ。
1. トークンの発行: GitLabの「User Settings」>「Access Tokens」へ。`api` スコープを付与して発行してください。
2. 動作確認: `curl` でエンドポイントを叩いてみましょう。
GitLabのGraphQLエンドポイントへ疎通確認
export GITLAB_TOKEN=”あなたのトークン”
curl -X POST https://gitlab.com/api/graphql \
-H “Authorization: Bearer $GITLAB_TOKEN” \
-H “Content-Type: application/json” \
-d ‘{“query”: “{ currentUser { name } }”}’
{“data”:{“currentUser”:{“name”:”あなたの名前”}}} が返ってくれば成功です！
—
3. 【実践】数百プロジェクトから「特定のラベル」のイシューを抽出する
ここからが本題です。GraphQLの真骨頂である「ネストしたクエリ」を使って、プロジェクトとイシューを同時並行で取得します。
以下のスクリプトは、指定したグループ配下の全プロジェクトから「`urgent`」というラベルがついたイシューを抽出するPythonの雛形です。
import requests
import csv
設定
GITLAB_URL = “https://gitlab.com/api/graphql”
TOKEN = “あなたのトークン”
GROUP_PATH = “your-namespace/your-group”
query = “””
query($groupPath: ID!) {
group(fullPath: $groupPath) {
projects {
nodes {
name
issues(labels: [“urgent”]) {
nodes {
title
webUrl
}
}
}
}
}
}
“””
response = requests.post(GITLAB_URL,
json={‘query’: query, ‘variables’: {‘groupPath’: GROUP_PATH}},
headers={‘Authorization’: f’Bearer {TOKEN}’})
data = response.json()[‘data’][‘group’][‘projects’][‘nodes’]
CSVへの出力処理
with open(‘urgent_issues.csv’, ‘w’, newline=”) as f:
writer = csv.writer(f)
writer.writerow([‘Project’, ‘Title’, ‘URL’])
for project in data:
for issue in project[‘issues’][‘nodes’]:
writer.writerow([project[‘name’], issue[‘title’], issue[‘webUrl’]])
print(“抽出完了！urgent_issues.csvを確認してください。”)
—
4. 現場で差がつく「GraphQL運用のハック」
初心者が陥りやすい罠と、それを回避するプロの作法を共有します。
- ページネーションを忘れない: デフォルトで取得できるのは100件までです。数百のリポジトリがある場合、`pageInfo` オブジェクトを使って `endCursor` を追いかけるカーソルベースのページネーション実装が必須です。これをサボるとデータが欠落します。
- GraphiQLを活用する: GitLabにはブラウザ上でクエリを試せる「GraphiQL」環境（`/explore/graphiql`）が標準で備わっています。ここでクエリを完成させてからコードに落とし込むのが最短距離です。
- リクエスト制限を意識する: APIにはレートリミットがあります。数百のリポジトリをループで叩く際は、Pythonなら `time.sleep` を挟むか、ライブラリの `retry` ロジックを組み込むなど、行儀よく振る舞いましょう。
—
最後に：あなただけの「自動化エンジン」を作ろう
GraphQLをマスターすれば、GitLabは単なるコード置き場から、「組織の活動を可視化する巨大なデータセット」に変わります。
最初は「特定のラベルの抽出」から始めてみてください。次に「マージリクエストのレビュー待ち時間を集計して、ボトルネックを特定する」といった分析に進めば、あなたのチームの生産性は劇的に向上するはずです。
「これをやれば楽になる」という直感を信じて、まずは一行、クエリを書いてみてください。応援しています！