内部API

内部APIは異なるGitLabコンポーネントによって使用され、他のコンシューマによって使用されることはありません。このドキュメントはGitLabコードベースで作業する人向けです。

このドキュメントには、GitLab Pagesが使用する内部APIはまだ含まれていません。

新しいエンドポイントの追加

APIエンドポイントは、適切な認証と作成者の許可を得て、デフォルトで外部からアクセスできるようにすべきです。新しい内部エンドポイントを追加する前に、そのAPIがより広いGitLabコミュニティにとって役に立つ可能性があり、外部からアクセスできるようにできるかどうかを検討してください。

内部 API エンドポイントを推奨する理由の一つは、そのようなエンドポイントを使うには外部のアクターが持つことのできない内部データが必要な場合です。例えば、内部 Pages API では、リクエストが内部であることを識別するシークレットトークンを使ったり、より広いコミュニティには公開されていない公開鍵でリクエストに署名したりすることがあります。

何かを内部APIに分離するもう一つの理由は、そのようなAPIエンドポイントへのリクエストがエッジ（公開）ロードバランサーを経由してはならない場合です。こうすることで、エンドポイントがどのようにアクセスされているのかについて、異なるレート制限ルールやポリシーを設定することができます。

認証

これらのメソッドはすべて共有シークレットを使って認証されます。このシークレットは、config/gitlab.yml で設定されたパスにあるファイルに保存されます。デフォルトでは、railsアプリのルートにある.gitlab_shell_secret

このトークンを使って認証するには、クライアントが

  1. そのファイルの内容を読み取ります。
  2. ファイルの内容を使用して、JSON Web Token (JWT) を生成します。
  3. Gitlab-Shell-Api-Request ヘッダーに JWT を渡します。

Git 認証

Gitalyと GitLab Shellがリポジトリへのアクセスを確認するために呼び出します。

  • GitLab Shellから呼ばれた場合：変更は渡されず、内部APIはリクエストをGitalyに渡すために必要な情報を返信します。
  • ** pre-receive フック**で Gitaly から呼び出された場合：変更が渡され、プッシュが許可されるかどうか検証されます。

呼び出しは1回50秒に制限されています。

このエンドポイントについては、対象範囲が広いため、独自のページで詳しく説明しています。

POST /internal/allowed
属性種類必須説明
key_id文字列です。いいえGitLab Shellに接続するためのSSHキーのID。
username文字列です。いいえGitLab Shellへの接続に使用する証明書のユーザー名
project文字列です。no (gl_repository が渡された場合)プロジェクトへのパス
gl_repository文字列です。no (project が渡された場合)リポジトリの識別子。project-7
protocol文字列です。yesGitLab Shellから呼び出す場合はSSH、Gitalyから呼び出す場合はHTTPまたはSSHです。
action文字列です。yes実行中の Git コマンド (git-upload-pack,git-receive-pack,git-upload-archive)
changes文字列です。yes <oldrev> <newrev> <refname> Gitalyから呼び出された場合はマジック文字列_any GitLab Shellから呼び出された場合はマジック文字列
check_ip文字列です。いいえGitLab Shellの呼び出し元のIPアドレス

リクエストの例

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" \
     "http://localhost:3001/api/v4/internal/allowed"

応答例

{
  "status": true,
  "gl_repository": "project-3",
  "gl_project_path": "gnuwget/wget2",
  "gl_id": "user-1",
  "gl_username": "root",
  "git_config_options": [],
  "gitaly": {
    "repository": {
      "storage_name": "default",
      "relative_path": "@hashed/4e/07/4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce.git",
      "git_object_directory": "",
      "git_alternate_object_directories": [],
      "gl_repository": "project-3",
      "gl_project_path": "gnuwget/wget2"
    },
    "address": "unix:/Users/bvl/repos/gitlab/gitaly.socket",
    "token": null
  },
  "gl_console_messages": []
}

既知の消費者

  • Gitaly
  • GitLab シェル

LFS 認証

リポジトリが SSH 経由でアクセスされたときに LFS クライアントに情報を提供するために GitLab Shell から呼び出されるエンドポイントです。

属性種類必須説明
key_id文字列です。いいえGitLab Shellに接続するためのSSHキーのID。
username文字列です。いいえGitLab Shellへの接続に使用する証明書のユーザー名
project文字列です。いいえプロジェクトへのパス

リクエストの例

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "key_id=11&project=gnuwget/wget2" "http://localhost:3001/api/v4/internal/lfs_authenticate"

{
  "username": "root",
  "lfs_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImFjdG9yIjoicm9vdCJ9LCJqdGkiOiIyYWJhZDcxZC0xNDFlLTQ2NGUtOTZlMi1mODllYWRiMGVmZTYiLCJpYXQiOjE1NzAxMTc2NzYsIm5iZiI6MTU3MDExNzY3MSwiZXhwIjoxNTcwMTE5NDc2fQ.g7atlBw1QMY7QEBVPE0LZ8ZlKtaRzaMRmNn41r2YITM",
  "repository_http_path": "http://localhost:3001/gnuwget/wget2.git",
  "expires_in": 1800
}

既知の消費者

  • GitLab シェル

作成者の鍵チェック

このエンドポイントはGitLab Shell authorized keys checkによって呼び出されます。このエンドポイントはOpenSSHやGitLab SSHDによってSSHキーを高速に検索するために呼び出されます。

属性種類必須説明
key文字列です。yes公開鍵認証に使用する作成者鍵。
GET /internal/authorized_keys

リクエストの例

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/authorized_keys?key=<key>"

応答例

{
  "id": 11,
  "title": "admin@example.com",
  "key": "ssh-rsa ...",
  "created_at": "2019-06-27T15:29:02.219Z"
}

既知の消費者

  • GitLab シェル

ユーザー ID またはキーを取得します。

このエンドポイントは、ユーザーがssh git@gitlab.com を実行するときに使用されます。SSH キーに関連付けられたユーザーを検出します。

属性種類必須説明
key_id整数。いいえauthorized-keysファイルまたは/authorized_keys のチェックで見つかったSSHキーのID。
username文字列です。いいえGitLab Shell が証明書を使用して認証する際に使用する、検索するユーザーのユーザー名。
GET /internal/discover

リクエストの例

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/discover?key_id=7"

応答例

{
  "id": 7,
  "name": "Dede Eichmann",
  "username": "rubi"
}

既知の消費者

  • GitLab シェル

インスタンス情報

インスタンスに関する一般的な情報を取得します。これは Geo ノードがお互いの情報を取得するために使用します。

GET /internal/check

リクエストの例

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/check"

応答例

{
  "api_version": "v4",
  "gitlab_version": "12.3.0-pre",
  "gitlab_rev": "d69c988e6a6",
  "redis": true
}

既知の消費者

  • GitLab Geo
  • GitLab Shellのbin/check
  • Gitaly

SSHキーを使用した新しい2FA回復コードの取得

これはGitLab Shellから呼び出され、ユーザーがSSHキーに基づいて新しい2FA回復コードを取得できるようにします。

属性種類必須説明
key_id整数。いいえauthorized-keysファイルまたは/authorized_keys のチェックで見つかったSSHキーのID。
user_id整数。いいえ新しい回復コードを生成するための非推奨ユーザーID
GET /internal/two_factor_recovery_codes

リクエストの例

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "key_id=7" "http://localhost:3001/api/v4/internal/two_factor_recovery_codes"

応答例

{
  "success": true,
  "recovery_codes": [
    "d93ee7037944afd5",
    "19d7b84862de93dd",
    "1e8c52169195bf71",
    "be50444dddb7ca84",
    "26048c77d161d5b7",
    "482d5c03d1628c47",
    "d2c695e309ce7679",
    "dfb4748afc4f12a7",
    "0e5f53d1399d7979",
    "af04d5622153b020"
  ]
}

既知の消費者

  • GitLab シェル

新しい個人アクセストークンを取得します

これは GitLab Shell から呼び出され、ユーザーが新しい個人アクセストークンを生成できるようにします。

属性種類必須説明
name文字列です。yes新しいトークンの名前
scopes文字列配列yes新しいトークンの作成者スコープ。有効なトークンのスコープでなければなりません。
expires_at文字列です。いいえ新しいトークンの有効期限
key_id整数。いいえauthorized-keysファイルまたは/authorized_keys のチェックで見つかったSSHキーのID。
user_id整数。いいえ新しいトークンを生成するユーザーID
POST /internal/personal_access_token

リクエストの例

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" \
     "http://localhost:3001/api/v4/internal/personal_access_token"

応答例

{
  "success": true,
  "token": "Hf_79B288hRv_3-TSD1R",
  "scopes": ["read_user","read_repository"],
  "expires_at": "2020-07-24"
}

既知の消費者

  • GitLab シェル

エラー追跡リクエストの認証

このエンドポイントは、エラー追跡 Go REST API アプリケーションがプロジェクトを認証するために呼び出されます。 > GitLab 15.1で導入されました。

属性種類必須説明
project_id整数。yes関連するキーを持つプロジェクトのID。
public_key文字列です。yes統合エラー追跡機能によって生成された公開鍵。
POST /internal/error_tracking/allowed

リクエストの例

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "project_id=111&public_key=generated-error-tracking-key" \
          "http://localhost:3001/api/v4/internal/error_tracking/allowed"

応答例

{ "enabled": true }

既知の消費者

  • OpsTrace

事前受信時のカウンターのインクリメント

これはGitalyフックから呼び出され、プッシュを受け付ける可能性のある参照カウンタを増やします。

属性種類必須説明
gl_repository文字列です。yesプッシュを受け取るリポジトリのリポジトリ識別子
POST /internal/pre_receive

リクエストの例

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive"

応答例

{
  "reference_counter_increased": true
}

ポストレシーブ

プッシュ受信後にGitalyから呼び出されます。これはSidekiqのPostReceive-workerをトリガーし、渡されたプッシュオプションを処理し、ユーザーに表示する必要があるメッセージを含むレスポンスを構築します。

属性種類必須説明
identifier文字列です。yes user-[id] またはkey-[id] プッシュを実行するユーザーの識別
gl_repository文字列です。yesプッシュ先のリポジトリの識別子
push_options文字列配列いいえプッシュオプションの配列
changes文字列です。いいえ oldrev newrev refname\n 。
POST /internal/post_receive

リクエストの例：

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "gl_repository=project-7" --data "identifier=user-1" \
     --data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" \
     "http://localhost:3001/api/v4/internal/post_receive"

応答例

{
  "messages": [
    {
      "message": "Hello from post-receive",
      "type": "alert"
    }
  ],
  "reference_counter_decreased": true
}

GitLab エージェントのエンドポイント

  • GitLab 13.4 で導入されました。
  • この機能は GitLab.com にはデプロイされていません。
  • 本番環境での使用は推奨されていません。

以下のエンドポイントは GitLab エージェントサーバー (kas) によって様々な目的で使用されます。

これらのエンドポイントはすべてJWTを使って認証されます。JWTシークレットはconfig/gitlab.yml で指定されたファイルに保存されます。デフォルトでは、GitLab Railsアプリのルートにある.gitlab_kas_secret というファイルに保存されます。

GitLabエージェント情報

GitLab agent server (kas) kasからコールされkas、指定されたエージェントトークンのエージェント情報を取得 kasします。エージェントの設定を取得・更新するために、kasエージェントのプロジェクトのGitaly接続情報を返します kas。

GET /internal/kubernetes/agent_info

リクエストの例：

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info"

GitLab エージェントのプロジェクト情報

GitLab agent server (kas) kasからコールされkas、指定されたエージェントトークンのプロジェクト情報を取得 kasします。kasこれは要求されたプロジェクトのGitaly接続を返します。GitLabは kasこれを使用して、同期するプロジェクトリポジトリからKubernetesリソースをフェッチするようにエージェントを設定します。

公開プロジェクトのみがサポートされています。非公開プロジェクトの場合、エージェントの作成者はまだ実装されていません。

属性種類必須説明
id整数/文字列yes プロジェクトのIDまたはURLエンコードされたパス 
GET /internal/kubernetes/project_info

リクエストの例：

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7"

GitLabエージェントの使用メトリクス

GitLabエージェントサーバ(kas)から呼び出され、使用メトリクスカウンタを増やします。

属性種類必須説明
countersハッシュいいえカウンターのハッシュ
counters["k8s_api_proxy_request"]整数。いいえ k8s_api_proxy_request カウンターを増加させる数値。
counters["gitops_sync"]整数。いいえ gitops_sync カウンターを増加させる数値。
counters["flux_git_push_notifications_total"]整数。いいえ flux_git_push_notifications_total カウンターを増加させる数値。
counters["k8s_api_proxy_requests_via_ci_access"]整数。いいえ k8s_api_proxy_requests_via_ci_access カウンターを増加させる数値。
counters["k8s_api_proxy_requests_via_user_access"]整数。いいえ k8s_api_proxy_requests_via_user_access カウンターを増加させる数値。
counters["k8s_api_proxy_requests_via_pat_access"]整数。いいえ k8s_api_proxy_requests_via_pat_access カウンターを増加させる数値。
unique_countersハッシュいいえ一意な番号の配列
unique_counters["agent_users_using_ci_tunnel"]整数配列。いいえ agent_users_using_ci_tunnel メトリックイベントを追跡するためにCIトンネルと相互作用した一意のユーザーIDのセット。
unique_counters["k8s_api_proxy_requests_unique_users_via_ci_access"]整数配列。いいえ k8s_api_proxy_requests_unique_users_via_ci_access メトリックイベントを追跡するために、ci_access を介して CI トンネルと相互作用した一意のユーザー ID のセット。
unique_counters["k8s_api_proxy_requests_unique_agents_via_ci_access"]整数配列。いいえ k8s_api_proxy_requests_unique_agents_via_ci_access メトリックイベントを追跡するために、ci_access を介して CI トンネルと相互作用した一意のエージェント ID のセット。
unique_counters["k8s_api_proxy_requests_unique_users_via_user_access"]整数配列。いいえ k8s_api_proxy_requests_unique_users_via_user_access メトリックイベントを追跡するために、user_access を介して CI トンネルと相互作用した一意のユーザー ID のセット。
unique_counters["k8s_api_proxy_requests_unique_agents_via_user_access"]整数配列。いいえ k8s_api_proxy_requests_unique_agents_via_user_access メトリックイベントを追跡するために、user_access を介して CI トンネルと相互作用した一意のエージェント ID のセット。
unique_counters["k8s_api_proxy_requests_unique_users_via_pat_access"]整数配列。いいえ k8s_api_proxy_requests_unique_users_via_pat_access メトリックイベントを追跡するために PAT 経由で KAS Kubernetes API プロキシを使用した一意のユーザー ID のセット。
unique_counters["k8s_api_proxy_requests_unique_agents_via_pat_access"]整数配列。いいえ k8s_api_proxy_requests_unique_agents_via_pat_access メトリックイベントを追跡するために PAT 経由で KAS Kubernetes API プロキシを使用した一意のエージェント ID のセット。
unique_counters["flux_git_push_notified_unique_projects"]整数配列。いいえ flux_git_push_notified_unique_projects メトリックイベントを追跡するために、Flux ワークロードを調整するよう通知された、一意のプロジェクト ID のセット。
POST /internal/kubernetes/usage_metrics

リクエストの例：

curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Content-Type: application/json" \
     --data '{"counters": {"gitops_sync":1}}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics"

スターボード脆弱性の作成

GitLabエージェントサーバー(kas)からコールされ、Starboard脆弱性レポートからセキュリティ脆弱性を作成します。このリクエストは冪等です。同じデータを持つ複数のリクエストが一つの脆弱性を作成します。レスポンスには、作成された脆弱性発見のUUIDがコンテナで返されます。

属性種類必須説明
vulnerabilityハッシュyesセキュリティレポートスキーマvulnerability フィールドに一致する脆弱性データ。
scannerハッシュyesセキュリティレポートスキーマscanner フィールドに一致するスキャナデータ。
PUT internal/kubernetes/modules/starboard_vulnerability

リクエストの例：

curl --request PUT --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability" \
     --data '{
  "vulnerability": {
    "name": "CVE-123-4567 in libc",
    "severity": "high",
    "confidence": "unknown",
    "location": {
      "kubernetes_resource": {
        "namespace": "production",
        "kind": "deployment",
        "name": "nginx",
        "container": "nginx"
      }
    },
    "identifiers": [
      {
        "type": "cve",
        "name": "CVE-123-4567",
        "value": "CVE-123-4567"
      }
    ]
  },
  "scanner": {
    "id": "starboard_trivy",
    "name": "Trivy (via Starboard Operator)",
    "vendor": "GitLab"
  }
}'

応答例

{
  "uuid": "4773b2ee-5ba5-5e9f-b48c-5f7a17f0faac"
}

スターボードの脆弱性の解決

GitLabエージェントサーバー(kas)から呼び出され、Starboardのセキュリティ脆弱性を解決します。見つかったUUIDのリストを受け取り、そのリストで特定されなかったStarboardの脆弱性をすべて解決済みとしてマークします。

属性種類必須説明
uuids文字列配列yes Create Starboardの脆弱性対応から収集された、検出された脆弱性のUUID。
POST internal/kubernetes/modules/starboard_vulnerability/scan_result

リクエストの例：

curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_result" \
     --data '{ "uuids": ["102e8a0a-fe29-59bd-b46c-57c3e9bc6411", "5eb12985-0ed5-51f4-b545-fd8871dc2870"] }'

スキャン実行ポリシー

GitLabエージェントサーバ(kas)から呼び出され、エージェントトークンに属するプロジェクトに対して設定されたscan_execution_policies を取得します。GitLabkas はこれを使用して、ポリシーに基づいてKubernetesクラスタ内のイメージをスキャンするようにエージェントを設定します。

GET /internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies

リクエストの例：

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies"

応答例

{
  "policies": [
    {
      "name": "Policy",
      "description": "Policy description",
      "enabled": true,
      "yaml": "---\nname: Policy\ndescription: 'Policy description'\nenabled: true\nactions:\n- scan: container_scanning\nrules:\n- type: pipeline\n  branches:\n  - main\n",
      "updated_at": "2022-06-02T05:36:26+00:00"
    }
  ]
}

ポリシー設定

GitLabエージェントサーバ(kas)から呼び出され、エージェントトークンに属するプロジェクトに対して設定されたpolicies_configuration を取得します。GitLabkas はこれを使用して、設定に基づいてKubernetesクラスタ内のイメージをスキャンするようにエージェントを設定します。

GET /internal/kubernetes/modules/starboard_vulnerability/policies_configuration

リクエストの例：

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/policies_configuration"

応答例

{
  "configurations": [
    {
      "cadence": "30 2 * * *",
      "namespaces": [
        "namespace-a",
        "namespace-b"
      ],
      "updated_at": "2022-06-02T05:36:26+00:00"
    }
  ]
}

サブスクリプション

Subscriptions エンドポイントは、CustomersDot(customers.gitlab.com) によって、GitLab.com 内の個人ネームスペースやトップレベルグループに対して、トライアルやアドオン購入を含むサブスクリプションを適用するために使用されます。

サブスクリプションの作成

サブスクリプションを作成するにはPOSTコマンドを使用します。

POST /namespaces/:id/gitlab_subscription
属性種類必須説明
start_date期日yes購読開始日
end_date期日いいえ購読終了日
plan_code文字列です。いいえサブスクリプション・ティアコード
seats整数。いいえ予約席数
max_seats_used整数。いいえ直近1ヶ月の最高アクティブユーザー数
auto_renewbooleanいいえ購読終了日に購読を自動更新するかどうか
trialbooleanいいえサブスクリプションがトライアルかどうか
trial_starts_on期日いいえ裁判開始日
trial_ends_on期日いいえ試験終了日

リクエストの例

curl --request POST --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?start_date="2020-07-15"&plan="premium"&seats=10"

応答例

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
  },
  "usage": {
    "seats_in_subscription":10,
    "seats_in_use":1,
    "max_seats_used":0,
    "seats_owed":0
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":null,
    "trial_ends_on":null
  }
}

サブスクリプションの更新

既存のサブスクリプションを更新するには、PUTコマンドを使用します。

PUT /namespaces/:id/gitlab_subscription
属性種類必須説明
start_date期日いいえ購読開始日
end_date期日いいえ購読終了日
plan_code文字列です。いいえサブスクリプション・ティアコード
seats整数。いいえ予約席数
max_seats_used整数。いいえ直近1ヶ月の最高アクティブユーザー数
auto_renewbooleanいいえ購読終了日に購読を自動更新するかどうか
trialbooleanいいえサブスクリプションがトライアルかどうか
trial_starts_on期日いいえ裁判の開始日。trialがtrueの場合は必須。
trial_ends_on期日いいえ試験終了日

リクエストの例

curl --request PUT --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?max_seats_used=0"

応答例

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
  },
  "usage": {
    "seats_in_subscription":80,
    "seats_in_use":82,
    "max_seats_used":0,
    "seats_owed":2
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":"2021-07-15",
    "trial_ends_on":null
  }
}

サブスクリプションの取得

既存のサブスクリプションを表示するには、GETコマンドを使用します。

GET /namespaces/:id/gitlab_subscription

リクエストの例

curl --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription"

応答例

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
    "exclude_guests":false,
  },
  "usage": {
    "seats_in_subscription":80,
    "seats_in_use":82,
    "max_seats_used":82,
    "seats_owed":2
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":"2021-07-15",
    "trial_ends_on":null
  }
}

既知の消費者

  • カスタマーズドット

サブスクリプションのアドオン購入（ストレージとコンピュートパックを除く）

サブスクリプションアドオン購入エンドポイントは、CustomersDot(customers.gitlab.com) によって、個人のネームスペースやGitLab.com内のトップレベルグループへのコード提案のようなサブスクリプションアドオン購入を適用するために使用されます。ストレージやコンピュートパックの購入には使用されません。

サブスクリプションのアドオン購入を作成

定期購入アドオンを作成するには、POST コマンドを使用します。

POST /namespaces/:id/subscription_add_on_purchase/:add_on_name
属性種類必須説明
quantity整数。yesサブスクリプションアドオン購入のユニット数（例：コード提案アドオンのシート数）
expires_on期日yesサブスクリプションアドオン購入の有効期限
purchase_xid文字列です。yesサブスクリプションアドオン購入の識別子（例：コード提案アドオンのサブスクリプション名）

リクエストの例

curl --request POST --header "PRIVATE-TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions?&quantity=10&expires_on="2024-07-15"&purchase_xid="A-S12345678""

応答例

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":10,
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678"
}

定期購入アドオンの更新

既存の定期購入アドオンを更新するには、PUTコマンドを使用します。

PUT /namespaces/:id/subscription_add_on_purchase/:add_on_name
属性種類必須説明
quantity整数。いいえサブスクリプションアドオン購入のユニット数（例：コード提案アドオンのシート数）
expires_on期日yesサブスクリプションアドオン購入の有効期限
purchase_xid文字列です。いいえサブスクリプションアドオン購入の識別子（例：コード提案アドオンのサブスクリプション名）

リクエストの例

curl --request PUT --header "PRIVATE-TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions?&quantity=15&expires_on="2024-07-15"&purchase_xid="A-S12345678""

応答例

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":15,
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678"
}

サブスクリプションのアドオン購入の取得

既存の定期購入アドオンを表示するには、GET コマンドを使用します。

GET /namespaces/:id/subscription_add_on_purchase/:add_on_name

リクエストの例

curl --header "PRIVATE-TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions"

応答例

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":15,
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678"
}

既知の消費者

  • カスタマーズドット

保管制限の除外

ネームスペースのストレージ制限除外エンドポイントは、GitLab.comのトップレベルのネームスペースのストレージ制限除外を管理します。これらのエンドポイントはGitLab.comの管理エリアでのみ利用できます。

ストレージ制限除外の取得

すべてのNamespaces::Storage::LimitExclusion レコードを取得するには、GET リクエストを使用します。

GET /namespaces/storage/limit_exclusions

リクエストの例

curl --request GET \
  --url "https://gitlab.com/v4/namespaces/storage/limit_exclusions" \
  --header 'PRIVATE-TOKEN: <admin access token>'

応答例

[
    {
      "id": 1,
      "namespace_id": 1234,
      "namespace_name": "A Namespace Name",
      "reason": "a reason to exclude the Namespace"
    },
    {
      "id": 2,
      "namespace_id": 4321,
      "namespace_name": "Another Namespace Name",
      "reason": "another reason to exclude the Namespace"
    },
]

ストレージ制限の除外を作成

POST リクエストを使用してNamespaces::Storage::LimitExclusionを作成します。

POST /namespaces/:id/storage/limit_exclusion
属性種類必須説明
reason文字列です。yes名前空間を除外する理由。

リクエストの例

curl --request POST \
  --url "https://gitlab.com/v4/namespaces/123/storage/limit_exclusion" \
  --header 'Content-Type: application/json' \
  --header 'PRIVATE-TOKEN: <admin access token>' \
  --data '{
    "reason": "a reason to exclude the Namespace"
  }'

応答例

{
  "id": 1,
  "namespace_id": 1234,
  "namespace_name": "A Namespace Name",
  "reason": "a reason to exclude the Namespace"
}

保存制限除外の削除

ネームスペースのNamespaces::Storage::LimitExclusion を削除するには、DELETE 要求を使用します。

DELETE /namespaces/:id/storage/limit_exclusion

リクエストの例

curl --request DELETE \
  --url "https://gitlab.com/v4/namespaces/123/storage/limit_exclusion" \
  --header 'PRIVATE-TOKEN: <admin access token>'

応答例

204

既知の消費者

  • GitLab.com管理エリア

コンピュートクォータのプロビジョニング

GitLab 16.1で “CI/CD minutes “から “compute quota “と “compute minutes “に名称変更。

コンピュートクォータエンドポイントは、CustomersDot(customers.gitlab.com) がGitLab.comの個人ネームスペースやトップレベルグループにコンピュート分の追加パックを適用するために使用します。

追加パックの作成

追加パックを作成するにはPOSTコマンドを使用します。

POST /namespaces/:id/minutes
属性種類必須説明
packsアレイyes購入したコンピュートパックの配列
packs[expires_at]期日yes購入パックの有効期限
packs[number_of_minutes]整数。yes追加計算分数
packs[purchase_xid]文字列です。yes購入のユニークID

リクエストの例

curl --request POST \
  --url "http://localhost:3000/api/v4/namespaces/123/minutes" \
  --header 'Content-Type: application/json' \
  --header 'PRIVATE-TOKEN: <admin access token>' \
  --data '{
    "packs": [
      {
        "number_of_minutes": 10000,
        "expires_at": "2022-01-01",
        "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
      }
    ]
  }'

応答例

[
  {
    "namespace_id": 123,
    "expires_at": "2022-01-01",
    "number_of_minutes": 10000,
    "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
  }
]

追加パックの移動

追加パックをあるネームスペースから別のネームスペースに移動するには、PATCH コマンドを使用します。

PATCH /namespaces/:id/minutes/move/:target_id
属性種類必須説明
id文字列です。yesパックを転送するネームスペースのID
target_id文字列です。yesパックの転送先ネームスペースのID

リクエストの例

curl --request PATCH \
  --url "http://localhost:3000/api/v4/namespaces/123/minutes/move/321" \
  --header 'PRIVATE-TOKEN: <admin access token>'

応答例

{
  "message": "202 Accepted"
}

既知の消費者

  • カスタマーズドット

今後の調整

upcoming_reconciliations エンドポイントは、CustomersDot(customers.gitlab.com) がネームスペースの今後の照合を更新するために使用します。

更新upcoming_reconciliations

upcoming_reconciliationsを更新するには、PUT コマンドを使用します。

PUT /internal/upcoming_reconciliations
属性種類必須説明
upcoming_reconciliationsアレイyes今後の照合の配列

各配列要素にはコンテナが含まれます：

属性種類必須説明
namespace_id整数。yes照合する名前空間のID
next_reconciliation_date期日yes次回の照合日
display_alert_from期日yes和解のアラートを表示する開始日

リクエストの例

curl --request PUT --header "PRIVATE-TOKEN: <admin_access_token>" --header "Content-Type: application/json" \
     --data '{"upcoming_reconciliations": [{"namespace_id": 127, "next_reconciliation_date": "13 Jun 2021", "display_alert_from": "06 Jun 2021"}, {"namespace_id": 129, "next_reconciliation_date": "12 Jun 2021", "display_alert_from": "05 Jun 2021"}]}' \
     "https://gitlab.com/api/v4/internal/upcoming_reconciliations"

応答例

200

を削除します。upcoming_reconciliation

upcoming_reconciliationを削除するには、DELETE コマンドを使用します。

DELETE /internal/upcoming_reconciliations
属性種類必須説明
namespace_id整数。yesGitLab.comネームスペースのIDで、今後のリコンサイルがないもの。

リクエストの例

curl --request DELETE \
  --url "http://localhost:3000/api/v4/internal/upcoming_reconciliations?namespace_id=22" \
  --header 'PRIVATE-TOKEN: <admin_access_token>'

応答例

204

既知の消費者

  • カスタマーズドット

グループSCIM API

GitLab 11.10で導入されました。

グループSCIM APIはRFC7644プロトコルを実装しています。このAPIはSCIMプロバイダインテグレーションのためのシステム用であるため、予告なく変更されることがあります。

このAPIを使用するには、グループのグループSSOを有効にしてください。この API は、SCIM for Group SSOが有効になっている場合にのみ使用されます。SCIM アイデンティティを作成するための前提条件です。

この API はメインの SCIM APIやインスタンス SCIM API とは異なります。

SCIM プロビジョニング済みユーザーの一覧の取得

このエンドポイントは SCIM 同期メカニズムの一部として使用されます。ユーザのextern_uid と一致する一意な ID に基づいた単一のユーザのみを返します。

GET /api/scim/v2/groups/:group_path/Users

パラメータを指定します：

属性種類必須説明
filter文字列です。いいえ フィルタ式。
group_path文字列です。yesグループへのフルパス。
startIndex整数。いいえどこから結果を返すかを示す1ベースのインデックス。1未満の値は1と解釈されます。
count整数。いいえクエリ結果の最大数を指定します。
note
ページ分割は、他の場所で使われている GitLab のページ分割ではなくSCIM の仕様に従います。リクエストの間でレコードが変更されると、ページが別のページに移動してレコードがなかったり、前のリクエストのレコードを繰り返したりする可能性があります。

リクエストの例

curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \
     --header "Authorization: Bearer <your_scim_token>" \
     --header "Content-Type: application/scim+json"

応答例

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "itemsPerPage": 20,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
      "active": true,
      "name.formatted": "Test User",
      "userName": "username",
      "meta": { "resourceType":"User" },
      "emails": [
        {
          "type": "work",
          "value": "name@example.com",
          "primary": true
        }
      ]
    }
  ]
}

単一の SCIM プロビジョニング済みユーザーを取得します。 

GET /api/scim/v2/groups/:group_path/Users/:id

パラメータを指定します：

属性種類必須説明
id文字列です。yesユーザーの外部UID。
group_path文字列です。yesグループへのフルパス。

リクエストの例

curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

応答例

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

SCIM プロビジョニングユーザーの作成 

POST /api/scim/v2/groups/:group_path/Users/

パラメータを指定します：

属性種類必須説明
externalId文字列です。yesユーザーの外部UID。
userName文字列です。yesユーザーのユーザー名。
emails文字列yes仕事のEメール
name文字列yesユーザー名。
meta文字列です。いいえリソースタイプ (User).

リクエストの例

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/groups/test_group/Users" \
     --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

応答例

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

成功した場合は201 ステータスコードを返します。

単一の SCIM プロビジョニングユーザの更新

更新可能なフィールド

SCIM/IDPフィールドGitLab フィールド
id/externalIdextern_uid
name.formatted name (削除しました)
emails\[type eq "work"\].value email (削除しました)
active active =の場合、アイデンティティ削除。false
userName username (削除しました)
PATCH /api/scim/v2/groups/:group_path/Users/:id

パラメータを指定します：

属性種類必須説明
id文字列です。yesユーザーの外部UID。
group_path文字列です。yesグループへのフルパス。
Operations文字列yes オペレーション式。

リクエストの例

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"replace","path":"id","value":"1234abcd"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

成功した場合は、204 ステータスコードとともに空のレスポンスを返します。

単一の SCIM プロビジョニングユーザーの削除

ユーザーの SSO ID とグループメンバーシップを削除します。

DELETE /api/scim/v2/groups/:group_path/Users/:id

パラメータを指定します：

属性種類必須説明
id文字列です。yesユーザーの外部UID。
group_path文字列です。yesグループへのフルパス。

リクエストの例

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

成功した場合は、204 ステータスコードとともに空のレスポンスを返します。

インスタンス SCIM API

GitLab 15.8で導入されました。

インスタンスSCIM APIはRFC7644プロトコルを実装しています。このAPIはSCIMプロバイダインテグレーションのためのシステム用であるため、予告なく変更されることがあります。

この API を使用するには、インスタンスのSAML SSOを有効にします。

この API は、メインの SCIM APIおよびグループの SCIM API とは異なります。

SCIM プロビジョニング済みユーザーの一覧の取得

このエンドポイントは SCIM 同期メカニズムの一部として使用されます。ユーザのextern_uid と一致する一意な ID に基づいた単一のユーザのみを返します。

GET /api/scim/v2/application/Users

パラメータを指定します：

属性種類必須説明
filter文字列です。いいえ フィルタ式。
startIndex整数。いいえどこから結果を返すかを示す1ベースのインデックス。1未満の値は1と解釈されます。
count整数。いいえクエリ結果の最大数を指定します。
note
ページ分割は、他の場所で使われている GitLab のページ分割ではなくSCIM の仕様に従います。リクエストの間でレコードが変更されると、ページが別のページに移動してレコードがなかったり、前のリクエストのレコードを繰り返したりする可能性があります。

リクエストの例

curl "https://gitlab.example.com/api/scim/v2/application/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \
     --header "Authorization: Bearer <your_scim_token>" \
     --header "Content-Type: application/scim+json"

応答例

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "itemsPerPage": 20,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
      "active": true,
      "name.formatted": "Test User",
      "userName": "username",
      "meta": { "resourceType":"User" },
      "emails": [
        {
          "type": "work",
          "value": "name@example.com",
          "primary": true
        }
      ]
    }
  ]
}

単一の SCIM プロビジョニング済みユーザーを取得します。 

GET /api/scim/v2/application/Users/:id

パラメータを指定します：

属性種類必須説明
id文字列です。yesユーザーの外部UID。

リクエストの例

curl "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

応答例

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

SCIM プロビジョニングユーザーの作成 

POST /api/scim/v2/application/Users

パラメータを指定します：

属性種類必須説明
externalId文字列です。yesユーザーの外部UID。
userName文字列です。yesユーザーのユーザー名。
emails文字列yes仕事のEメール
name文字列yesユーザー名。
meta文字列です。いいえリソースタイプ (User).

リクエストの例

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/application/Users" \
     --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

応答例

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

成功した場合は201 ステータスコードを返します。

単一の SCIM プロビジョニングユーザの更新

更新可能なフィールド

SCIM/IDPフィールドGitLab フィールド
id/externalIdextern_uid
active false の場合、ユーザーはブロックされますが、SCIM ID はリンクされたままです。
PATCH /api/scim/v2/application/Users/:id

パラメータを指定します：

属性種類必須説明
id文字列です。yesユーザーの外部UID。
Operations文字列yes オペレーション式。

リクエストの例

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"Update","path":"active","value":"false"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

成功した場合は、204 ステータスコードとともに空のレスポンスを返します。

単一の SCIM プロビジョニングユーザーの削除

ユーザーはldap_blocked ステータスになり、サインアウトされます。これは、ユーザーがサインインできない、コードをプッシュまたはプルできないことを意味します。

DELETE /api/scim/v2/application/Users/:id

パラメータを指定します：

属性種類必須説明
id文字列です。yesユーザーの外部UID。

リクエストの例

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

成功した場合は、204 ステータスコードとともに空のレスポンスを返します。

使用可能なフィルタ

RFC7644のフィルタリングセクションで指定された式にマッチします。

Filter説明
eq属性は指定された値と正確に一致します。

使用例：

id eq a-b-c-d

可能なオペレーション

RFC7644の更新セクションで指定されているオペレーションを実行します。

オペレーション説明
Replace属性の値が更新されます。
Add属性の値が更新されました。

使用例：

{ "op": "Add", "path": "name.formatted", "value": "New Name" }