--- title: "GitLab APIの使い方：トークン認証とcurl例・ページネーションとレート制限の実装【2026年11月】" url: "https://www.issoh.co.jp/tech/details/19681/" published: 2026-11-13 updated: 2026-11-13 categories: ["開発"] publisher: "株式会社一創" --- # GitLab APIの使い方：トークン認証とcurl例・ページネーションとレート制限の実装【2026年11月】 GitLab APIは、プロジェクトやIssue、マージリクエスト、パイプラインをHTTPで読み書きするための窓口で、REST API v4とGraphQL APIの2系統という構成になっているAPIです。この記事では、アクセストークンを`PRIVATE-TOKEN`ヘッダーで渡す認証から始めて、curlでのIssue作成とパイプライン起動、1ページ20件の既定を超えて全件を取るページネーション、python-gitlabでの実装、GitLab.comのレート制限と429への備えまでを順に示します。仕様と数値は2026年11月時点の公式ドキュメントにもとづいています。 ## まとめ：GitLab APIはPRIVATE-TOKENで認証しLinkヘッダーで全件を取る REST APIの呼び出しは`https://ホスト名/api/v4/`に続くパスに、トークンを`PRIVATE-TOKEN`ヘッダーで付けるだけです。読み取りだけなら`read_api`スコープで足り、IssueやMRを作るときに`api`へ広げます。401はトークンが無効、403はスコープか権限の不足と覚えておくと、エラーの切り分けが速くなります。 一覧系は既定で20件、最大100件しか返りません。全件を取るには応答の`Link`ヘッダーの`next`をたどります。1万件を超える一覧では件数ヘッダーが返らないため、対応するエンドポイントではキーセット方式への切り替えが必要です。GitLab.comでは認証済みAPIが1ユーザー毎分2,000件までで、超えると429と`Retry-After`が返るので、その秒数だけ待って再送する処理を最初から入れておきます。 ## GitLab APIの3つの窓口：REST API v4・GraphQL・glabの比較 ### REST API v4のベースURLとid・iid・URLエンコードしたパスの指定方法 [REST APIのドキュメント](https://docs.gitlab.com/api/rest/)によると、リクエストはGitLabのホスト名に`/api/v4`を続けたパスで送ります。GitLab.comなら`https://gitlab.com/api/v4/projects`、Self-Managedなら自社のホスト名に置き換えます。`v4`は後方互換性のない変更があるときだけ上がり、新しいエンドポイントの追加先は、引き続き同じv4です。 つまずきやすいのは識別子です。プロジェクトはIDの数値か、`グループ名/プロジェクト名`のパスで指定でき、パスを使うときは`/`を`%2F`に置き換えます。IssueやMRには全体で一意の`id`と、プロジェクト内の連番`iid`があり、URLに入れるのは画面に表示される`iid`のほうです。プロジェクトID 42のIssueで`id`が46、`iid`が5なら、`/projects/42/issues/5`が正しく、`/issues/46`は404になります。 ### RESTとGraphQLとglab apiの使い分け：取得件数とクエリ上限で選ぶ基準 呼び出し口は3つあります。迷ったらRESTから始めます。 | 呼び出し口 | エンドポイント | 向く用途 | 主な上限 | | ----------- | -------------- | ----------- | ---------------- | | REST API v4 | /api/v4/… | 一覧取得と更新全般 | 1ページ最大100件 | | GraphQL API | /api/graphql | 関連データを1回で取る | 複雑度250・30秒 | | glab api | RESTとGraphQL両方 | 手元での試行と調査 | REST・GraphQLに準ずる | [GraphQL APIのドキュメント](https://docs.gitlab.com/api/graphql/)では、認証済みのクエリ複雑度が250、1ページ100ノード、クエリ本文10,000文字、リクエストのタイムアウトが30秒と定められています。MRとその承認者とパイプラインの状態をまとめて取りたいならGraphQLが向き、単純な一覧や作成ならRESTのほうが書きやすいです。両者の一般的な違いは[REST APIとGraphQLの違いと選び方](https://www.issoh.co.jp/tech/details/3591/)で整理しています。 [glab api](https://docs.gitlab.com/cli/api/)はGitLab公式CLIのサブコマンドで、リポジトリ内で実行すると`:fullpath`や`:id`が現在のプロジェクトに置き換わり、`--paginate`で全ページを自動で取得します。CLIでのリリース作成は[GitLab Releaseの作り方（glabで自動作成する手順）](https://www.issoh.co.jp/tech/details/19665/)でも使っています。 ## GitLab APIのトークン認証：PRIVATE-TOKENヘッダーとスコープの選び方 ### 個人・プロジェクト・グループのトークンをヘッダーで渡すcurlの設定例 [REST API authentication](https://docs.gitlab.com/api/rest/authentication/)で推奨されている渡し方は`PRIVATE-TOKEN`ヘッダーです。`Authorization: Bearer`ヘッダーでも同じトークンが通り、OAuthのトークンはこちらで渡します。トークンの種類の選び方と発行手順は[GitLabのアクセストークン（種類の選び方と発行手順）](https://www.issoh.co.jp/tech/details/19675/)で扱っているので、ここでは発行済みのトークンを使う前提で進めます。 ``` # トークンは環境変数から読む。シェル履歴やスクリプトに直接書かない export GITLAB=https://gitlab.example.com/api/v4 export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx # 認証できているかを確認する（自分のユーザー情報が返れば成功） curl --silent --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" "${GITLAB}/user" | jq '{id, username}' # Bearer ヘッダーでも同じ結果になる curl --silent --header "Authorization: Bearer ${GITLAB_TOKEN}" "${GITLAB}/user" | jq '.username' ``` 古い記事には`?private_token=`のようにURLのクエリでトークンを渡す例が残っていますが、URLはプロキシやサーバーのアクセスログに残ります。ヘッダーで渡す形にそろえます。ヘッダーでの認証の一般的な考え方は[Bearer Tokenの書き方とJWTとの違い](https://www.issoh.co.jp/tech/details/4150/)を参照してください。 ### 401・403 insufficient\_scopeの判別とCIジョブトークン認証 認証まわりのエラーは、ステータスコードで原因の当たりが付きます。[Troubleshooting the REST API](https://docs.gitlab.com/api/rest/troubleshooting/)の一覧から、API利用の初期に出やすいものを抜き出すと次のとおりです。 | コード | よくある原因 | 確認すること | | --- | ------------------ | ---------------------- | | 401 | トークンの期限切れ・失効・打ち間違い | トークンの有効期限と値 | | 403 | スコープ不足か操作権限の不足 | 本文のinsufficient\_scope | | 404 | パスの誤りか閲覧権限なし | %2Fのエンコードとiid | | 429 | レート制限の超過 | Retry-Afterの秒数 | 403でスコープが足りない場合は、応答に`error="insufficient_scope"`が入り、本文と`WWW-Authenticate`ヘッダーに通るスコープが列挙されます。列挙されたもののどれか1つをトークンに足せば通ります。404は「存在しない」と「見る権限がない」を区別しないため、非公開プロジェクトでトークンのロールが足りないときも404です。ロールごとに許される操作は[GitLabの権限（ロール）：Guest〜Ownerの操作範囲と保護ブランチの設定手順](https://www.issoh.co.jp/tech/details/19683/)で確かめられます。 CIジョブの中からAPIを呼ぶなら、トークンを発行せずに`JOB-TOKEN: ${CI_JOB_TOKEN}`ヘッダーで認証できます。ただし使えるエンドポイントは一部だけという制約付きです。ジョブでの変数の渡し方は[GitLab CI/CDのrules・needs・変数の設定例](https://www.issoh.co.jp/tech/details/19661/)にまとめています。 ## curlで試すGitLab APIの基本操作：プロジェクト取得からIssue作成まで ### プロジェクト一覧とIssue一覧をcurlとjqで絞り込むGETリクエストの例 最初の一歩は、自分が参加しているプロジェクトの一覧です。[Projects API](https://docs.gitlab.com/api/projects/)の`membership=true`を付けないと、GitLab.comでは公開プロジェクト全体が対象になり、目的のものが見つかりません。 ``` # 参加しているプロジェクトのIDとパスを100件取る curl --silent --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \ "${GITLAB}/projects?membership=true&simple=true&per_page=100" \ | jq -r '.[] | "\(.id)\t\(.path_with_namespace)"' # パスで1件を指定する（/ は %2F に置き換える） curl --silent --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \ "${GITLAB}/projects/example-group%2Fapp" | jq '{id, default_branch}' # 未完了のbugラベル付きIssueを、11月以降に更新されたものに絞る curl --silent --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \ "${GITLAB}/projects/42/issues?state=opened&labels=bug&updated_after=2026-11-01T00:00:00Z&per_page=100" \ | jq -r '.[] | "#\(.iid) \(.title)"' ``` [Issues API](https://docs.gitlab.com/api/issues/)の`labels`はカンマ区切りで、複数指定すると「すべてのラベルを持つIssue」に絞られます。いずれかに一致させたい場合は、ラベルごとに分けて呼んでから手元で結合します。 ### IssueとパイプラインをPOSTで作成するリクエストボディとラベル・変数の指定 作成系は`api`スコープが必要です。パラメータはクエリでも送れますが、本文が長くなるとURLの長さ制限で414が返るため、JSONの本文で送る形にしておくと後で困りません。 ``` # Issueを作る（title は必須。存在しないラベル名を渡すと新しく作られる） curl --silent --request POST \ --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \ --header "Content-Type: application/json" \ --data '{"title":"夜間バッチの失敗を調査","description":"2026-11-12 02:00 のジョブが失敗","labels":"bug,batch","due_date":"2026-11-20"}' \ "${GITLAB}/projects/42/issues" | jq '{iid, web_url}' # main ブランチでパイプラインを起動し、変数 DEPLOY_ENV を渡す curl --silent --request POST \ --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \ --header "Content-Type: application/json" \ --data '{"ref":"main","variables":[{"key":"DEPLOY_ENV","value":"staging"}]}' \ "${GITLAB}/projects/42/pipeline" | jq '{id, status, web_url}' ``` [Pipelines API](https://docs.gitlab.com/api/pipelines/)では`ref`だけが必須で、`variables`は`key`と`value`を持つ配列です。`variable_type`を省いた場合の渡し方は環境変数です。存在しないラベル名が自動で作られる仕様は便利ですが、打ち間違いがそのままラベルとして増えるので、ラベル名はスクリプト側で固定の一覧から選ばせます。Issues APIでIssueをまとめて登録するスクリプト例は[GitLabのIssue（テンプレート・ラベル・ボードの設定例とAPIでの一括登録）](https://www.issoh.co.jp/tech/details/19685/)で扱っています。MRをAPIで作る場合の承認ルールとの関係は[GitLabのマージリクエストの承認ルール設定](https://www.issoh.co.jp/tech/details/19663/)で確認できます。 ## ページネーションで全件を取る実装：オフセット方式とキーセット方式 ### per\_page最大100・Linkとx-next-pageによるbash全件取得例 一覧系のAPIは、何も指定しないと`page=1`・`per_page=20`で返ります。`per_page`の最大は100で、それより多い件数は複数回に分けて取ります。応答ヘッダーの構成は`x-next-page`・`x-total`・`x-total-pages`と、`rel="next"`などを含む`Link`です。公式ドキュメントはURLを自分で組み立てず`Link`をたどるよう勧めています。 ``` #!/usr/bin/env bash # 未完了Issueを全件取得して1つのJSON配列にまとめる（オフセット方式） set -euo pipefail PID=42 page=1 rm -f page_*.json while [ -n "${page}" ]; do curl --silent --fail --dump-header headers.txt \ --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \ --output "page_${page}.json" \ "${GITLAB}/projects/${PID}/issues?state=opened&per_page=100&page=${page}" # 最後のページでは x-next-page が空になり、ループを抜ける page=$(grep -i '^x-next-page:' headers.txt | tr -d '\r' | awk '{print $2}') done jq -s 'add' page_*.json > issues.json jq 'length' issues.json ``` このスクリプトは、ページ数が多くない社内リポジトリならそのまま動きます。GitLab.comでは一部のページネーションヘッダーが返らない場合があると明記されているため、本番では次の節のように`Link`ヘッダーをたどる実装に寄せます。 ### 1万件超のx-total欠落とpagination=keysetへの切り替え条件 オフセット方式には2つの落とし穴があります。1つ目は件数で、結果が10,000件を超えると`x-total`・`x-total-pages`と`rel="last"`のリンクが返らなくなります。総ページ数を先に計算してから回す実装では、ここが停止する箇所です。2つ目は深さで、Self-Managedでは管理者がオフセットの上限を変えられるため、環境によっては後ろのページが取れません。 対策はキーセット方式です。`pagination=keyset`を付け、`order_by`と`sort`を必ず指定します。2026年11月時点で対応しているのはプロジェクト一覧（`order_by=id`のみ）、グループ一覧、プロジェクトのジョブ、監査イベント、リポジトリツリー（17.1以降）、プロジェクトのIssue（18.3以降）などです。次のページへのURLは`Link`ヘッダーにだけ入り、最後のページで`Link`が消えます。 ``` import os import time import requests GITLAB = "https://gitlab.example.com/api/v4" session = requests.Session() session.headers["PRIVATE-TOKEN"] = os.environ["GITLAB_TOKEN"] def get_all(url, params): """Link ヘッダーの next をたどって全件を返す。429 は Retry-After だけ待って再送する""" items = [] while url: r = session.get(url, params=params, timeout=30) if r.status_code == 429: time.sleep(int(r.headers.get("Retry-After", "60"))) continue r.raise_for_status() items.extend(r.json()) url = r.links.get("next", {}).get("url") params = None # next の URL にクエリが含まれるので 2 回目以降は付けない return items projects = get_all( f"{GITLAB}/projects", {"pagination": "keyset", "order_by": "id", "sort": "asc", "per_page": 100, "membership": "true"}, ) print(len(projects)) ``` キーセット方式に対応していないエンドポイントでも、この`get_all`はオフセット方式の`Link`をたどってそのまま動きます。件数が万単位になりうる一覧だけキーセットのパラメータを付ける、という使い分けで十分です。 ## GitLab APIのPython実装：python-gitlabとrequestsの選択 ### python-gitlab 8.6系のiterator=Trueによる大量データ取得例 Pythonで書くなら、公式のREST APIをそのまま包んだpython-gitlabが手早い選択肢です。2026年11月時点の[python-gitlabのドキュメント](https://python-gitlab.readthedocs.io/en/stable/api-usage.html)は8.6系で、`list()`を引数なしで呼ぶと最初の1ページしか返らない点が注意書きされています。 ``` import os import gitlab # pip install python-gitlab gl = gitlab.Gitlab( "https://gitlab.example.com", private_token=os.environ["GITLAB_TOKEN"], per_page=100, ) gl.auth() # 認証を確かめる。失敗すると例外になる project = gl.projects.get("example-group/app") # iterator=True は必要な分だけ順にページを取る。件数が多い一覧はこちらを使う for issue in project.issues.list(state="opened", labels=["bug"], iterator=True): print(issue.iid, issue.title) # 全件をリストで受け取りたいときは get_all=True mrs = project.mergerequests.list(state="merged", get_all=True) print(len(mrs)) ``` キーセット方式は`gitlab.Gitlab(url, token, pagination="keyset", order_by="id", per_page=100)`のようにクライアント生成時に指定します。ドキュメントには、執筆時点で動くのは`order_by="id"`だけと書かれています。 python-gitlabとrequestsの直書きのどちらを選ぶかは、触るリソースの数で決めます。Issue・MR・パイプラインなど複数のリソースをまたぐなら、型と例外が整っているpython-gitlabのほうが保守が楽です。1〜2本のエンドポイントを定期的に叩くだけなら、依存を増やさずに前節の`get_all`で足ります。 ## レート制限と429への備え：GitLab.comの上限値とRetry-Afterでの再試行 ### GitLab.com認証済みAPI毎分2,000件・Groups一覧毎分50件の現行上限 [GitLab.com rate limits](https://docs.gitlab.com/user/gitlab%5Fcom/rate%5Flimits/)に載っている、2026年11月時点で適用中の上限のうちAPIに関わるものは次のとおりです。 | 対象 | 上限 | | --------------- | ---------- | | 認証済みAPI（ユーザーごと） | 毎分2,000件 | | 未認証（IPアドレスごと） | 毎分500件 | | プロジェクト一覧 | 10分で2,000件 | | グループ内のプロジェクト一覧 | 毎分600件 | | 単一プロジェクトの取得 | 毎分400件 | | グループ一覧 | 毎分50件 | | プロジェクト・グループの作成 | 1日200件 | 表の一覧系はそれぞれ`GET /api/v4/projects`、`GET /api/v4/groups/:id/projects`、`GET /api/v4/projects/:id`、`GET /api/v4/groups`への呼び出しです。全体の毎分2,000件より先に、個別のエンドポイントの上限に当たります。特にグループ一覧は毎分50件と低く、グループごとにループして呼ぶ棚卸しスクリプトはすぐ429になる構造です。上限を超えると429とともに`Retry-After`（秒）と`RateLimit-ResetTime`が返るので、前節のコードのようにその秒数だけ待ちます。注意したいのは、Projects・Groups・Users APIの制限では残量を示すヘッダーが付かず、残量があるように見えても429が返る場合があることです。残量ヘッダーを見て速度を落とす実装だけでは防げないため、429を受けたら待つ処理は必ず入れます。 Self-Managedの上限は管理者が設定するもので、GitLab.comの値は当てはまりません。自社サーバーで構築する場合の全体像は[GitLabとは（構成要素・3つの提供形態）](https://www.issoh.co.jp/tech/details/19631/)で確認できます。 ### 2027年1月発効予定のプラン別上限とFreeのバースト毎分100件の影響 同じページには、プランごとの新しい上限が提案として載っています。認証済みユーザーの持続上限は1時間あたりFree 5,000件・Premium 15,000件・Ultimate 25,000件で、1分あたりのバースト上限はFreeのAPIが100件・Premiumが1,250件・Ultimateが2,000件です。発効はPremiumとUltimateで2027年1月が予定されており、それまでの間に一時的に有効にする期間を設けると案内されています。 現行の上限との低いほうが適用されるため、Freeで毎分数百件を投げているスクリプトは、新上限の適用後に止まる可能性があります。今のうちに、一覧はキーセット方式でまとめて取る、同じデータを繰り返し取らずに手元に保存する、という2点で呼び出し回数を減らしておきます。数値と発効時期は変わりうるので、運用前に同ページで最新の値を確認してください。 ## GitLab APIで自動化を組む判断：自前スクリプトで済む場面と見送る場面 ### 自前のAPIスクリプトで足りる条件とWebhook・CIジョブへ寄せるケース 自前でAPIを定期的に呼ぶスクリプトが向くのは、集計や棚卸しのように「決まった時刻に一覧を取って加工する」処理です。週次のIssue集計、期限切れトークンの洗い出し、パイプラインの失敗率の算出などは、この記事のコードの組み合わせで作れます。 逆に、イベントに反応する処理を定期実行の差分チェックで作るのは避けます。「MRが作られたら通知する」「パイプラインが失敗したらチケットを起票する」を1分ごとのポーリングで実装すると、呼び出し回数がレート制限を圧迫し、検知も最大1分遅れます。この場合の切り替え先は、WebhookでGitLabから通知を受ける形か、パイプラインの中のジョブでAPIを呼ぶ形です。リポジトリの内容に応じた処理なら、CIジョブの中で`CI_JOB_TOKEN`を使うのが手間も漏えいの危険も最小です。AIエージェントからGitLabを操作したいだけなら、自前でAPIを包まずに[GitLab MCPサーバーの接続設定](https://www.issoh.co.jp/tech/details/19635/)を使うほうが早く済みます。 ### 社内システム連携まで広げるときに設計で詰まる箇所と外部委託の判断 GitLabのIssueを社内のチケット管理や工数管理、顧客向けポータルとつなぐ段階になると、論点はAPIの呼び方から設計に移ります。詰まりやすいのは、どちらを正とするかの同期方向、二重登録を防ぐ外部IDの持ち方、トークンを人ではなくサービスアカウントに持たせる権限設計、429や障害で欠けたデータの再取得の4点です。ここを決めずにスクリプトを増やすと、退職者のトークンで動く連携や、どこにも記録が残らない同期処理が残ります。 連携先が2つ以上ある、もしくは止まると業務が止まる連携なら、最初に同期の設計を文書にしてから作ることを勧めます。一創の[API開発・システム連携](https://www.issoh.co.jp/service/system/api/)では、GitLabを含む既存システムのAPI仕様を確認したうえで、同期方式とエラー時の再処理まで含めた連携の設計と実装を引き受けています。 ## よくある質問 GitLab APIを使い始める段階でよく出る質問をまとめました。 ### GitLab APIは無料プランでも使えますか？ 利用可能です。REST APIとGraphQL APIはGitLab.comのFreeでも、Self-ManagedのCommunity Editionでも利用できます。ただし、APIで操作できるのはそのプランで使える機能に限られ、たとえばIssue作成時に担当者を配列で渡す`assignee_ids`は、Issues APIの表ではPremium以上の属性という位置付けです。GitLab.comのFreeではプロジェクト・グループアクセストークンが使えないため、自動化用のトークンは個人トークンかサービスアカウントで用意します。 ### GitLab APIのトークンにはどのスコープを付ければよいですか？ 一覧の取得や参照だけなら`read_api`で足ります。Issue・MR・パイプラインの作成や更新をするなら`api`が必要です。GraphQLもクエリは`read_api`、ミューテーションは`api`です。権限が足りないと403と`insufficient_scope`が返り、応答に必要なスコープが示されるので、それを見て足します。 ### プロジェクトIDはどこで確認できますか？ プロジェクトのトップページ右上にある縦三点リーダー（Actions）からCopy project IDを選ぶとコピーできます。APIで調べるなら`GET /projects/グループ名%2Fプロジェクト名`の応答の`id`を見ます。IDの代わりにURLエンコードしたパスをそのまま使うこともできますが、プロジェクトの移動や名前変更でパスは変わるため、長く動かすスクリプトでは数値のIDを使うほうが安全です。 ### 1回のリクエストで100件より多く取得できますか？ できません。REST APIの`per_page`の上限は100です。全件が必要な場合は`Link`ヘッダーの`next`をたどって複数回に分けて取得します。CLIで済ませるなら`glab api issues --paginate`で全ページを自動取得でき、`--output ndjson`を付けるとjqで1件ずつ処理できます。 ### GitLab APIのv3は使えますか？ 使えません。現在のREST APIはv4で、公式ドキュメントにv3の記載はありません。`/api/v3`を使う例は、古い版のドキュメントを公開し続けているサーバーや過去の解説記事に残っているものです。GitLabは後方互換性を壊す変更があるときだけメジャーバージョンを上げ、新しい機能は同じv4に追加していきます。古い記事のコードを使うときは、パスの`v3`と、クエリでトークンを渡す書き方の2点を直してから動かします。 ## 関連記事 - [GitLabのアクセストークン：種類の選び方と発行手順・スコープと有効期限の設定【2026年11月】](https://www.issoh.co.jp/tech/details/19675/)：APIで使うトークンの発行とローテーションの手順です - [GitLabの使い方：プロジェクト作成からIssue・MR・CI/CDまでの手順【2026年10月】](https://www.issoh.co.jp/tech/details/18874/)：APIで操作する対象を画面で1周して確かめられます - [GitLab CI/CDとは：.gitlab-ci.ymlの書き方とrules・needs・変数の設定例【2026年11月】](https://www.issoh.co.jp/tech/details/19661/)：パイプラインからAPIを呼ぶときの変数の扱いです - [GitLab MCPサーバーの接続設定：Claude Code・Cursorでの使い方とツール一覧【2026年11月】](https://www.issoh.co.jp/tech/details/19635/)：AIエージェントからGitLabを操作する場合の入口です - [GitHubとGitLabの違い｜ActionsとGitLab CIの対応表・料金・セルフホスト比較](https://www.issoh.co.jp/tech/details/4219/)：GitHubのAPIと並べて検討したいときに役立ちます --- 出典: [GitLab APIの使い方：トークン認証とcurl例・ページネーションとレート制限の実装【2026年11月】]()（株式会社一創）