正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。
ドキュメントに関する現在のご利用体験についてお聞かせください。アンケートにご協力ください。

ポリシー保存場所API

  • プラン: Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated
  • ステータス: 実験的機能

これは実験的機能です。エンドポイントは予告なく変更される場合があります。

このAPIを使用して、ポリシー保存場所でセキュリティポリシーを作成します。ポリシーは組織に属し、単一のトリガーに応答し、その動作を構成するルールとアクションを備えています。

これらのエンドポイントは、以下のすべてが真の場合にのみ利用可能です:

  • security_policies_v2機能フラグが有効になっている場合。
  • 管理者が、管理者 > 設定 > セキュリティとコンプライアンスでインスタンスのポリシー保存実験を有効にしている。
  • 組織が、organizationUpdate GraphQLミューテーションのpolicyStoreExperimentEnabled引数を通じて設定されるpolicy_store_experiment_enabled組織設定によりオプトインしていること。

これらのいずれかが真でない場合、エンドポイントは404 Not Foundを返します。インスタンスがセキュリティオーケストレーションポリシーのライセンスを持っていない場合、403 Forbiddenを返します。

カタログ

カタログエンドポイントは、ポリシーの構築元を記述し、対象となるすべての呼び出し元に同じ静的コンテンツを返します。呼び出し元は、その組織がsecurity_policies_v2機能フラグを有効にしている認証済みユーザーである必要があります。これが真でない場合、エンドポイントは404 Not Foundを返します。

すべてのトリガーを一覧表示

ポリシーが応答できるすべてのトリガーを一覧表示します。

GET /security/policy_store/triggers

成功した場合、200と次のレスポンス属性を返します:

属性タイプ説明
[].id文字列ポリシーを作成する際にtrigger_typeとして使用される、トリガーのID。
[].name文字列トリガーの表示名。

リクエスト例:

shell
curl --request GET \
  --url "https://gitlab.example.com/api/v4/security/policy_store/triggers"

レスポンス例:

json
[
  { "id": "deployment_requested", "name": "Deployment requested" },
  { "id": "environment_advanced", "name": "Environment advanced" },
  { "id": "deployment_promoted", "name": "Deployment promoted" }
]

すべてのアクションを一覧表示

ポリシーが実行できるすべてのアクションを一覧表示します。

GET /security/policy_store/actions

成功した場合、200と次のレスポンス属性を返します:

属性タイプ説明
[].id文字列アクションのID。
[].name文字列アクションの表示名。

リクエスト例:

shell
curl --request GET \
  --url "https://gitlab.example.com/api/v4/security/policy_store/actions"

レスポンス例:

json
[
  { "id": "block", "name": "Block" },
  { "id": "require_approval", "name": "Require approval" }
]

すべてのルールタイプを一覧表示

ポリシーの構築元となるすべてのルールタイプを一覧表示します。

GET /security/policy_store/rules

成功した場合、200と次のレスポンス属性を返します:

属性タイプ説明
[].id文字列ルールタイプのID。
[].name文字列ルールタイプの表示名。

リクエスト例:

shell
curl --request GET \
  --url "https://gitlab.example.com/api/v4/security/policy_store/rules"

レスポンス例:

json
[
  { "id": "custom", "name": "Custom" },
  { "id": "calendar", "name": "Calendar" },
  { "id": "environment", "name": "Environment" }
]

ポリシー

ポリシーエンドポイントへのすべての呼び出しは認証済みである必要があり、呼び出し元は組織のオーナーまたはインスタンス管理者である必要があります。組織を管理できない呼び出し元は403 Forbiddenを受け取り、組織をまったく表示できない呼び出し元は404 Not Foundを受け取ります。

別の組織に属するポリシーは、存在しないポリシーと区別できません。IDを使用して組織をまたいでポリシーを読み取ったり変更したりすることはできません。

ポリシースコープ

ポリシーは、スコープを持たない限り、どこにでも適用されます。スコープは次の2つの方法のいずれかで作成され、リクエストはいずれか一方のみを使用でき、両方を同時に使用することはできません:

  • policy_scope: GitLabがscope_regoにコンパイルする構造化されたデータ。
  • scope_rego: Regoプログラムとして直接提供され、作成されたとおりに保存されるもの。

両方を指定するリクエストは400 Bad Requestを返します。空のscope_regoは2番目の形式とは見なされないため、どちらの操作もpolicy_scopeと一緒にそれを受け入れます。ポリシーの作成では、空の値は省略した場合と同じ効果があります。ポリシーの更新では、作成されたプログラムを廃止し、policy_scopeから新しいプログラムをコンパイルします。

スコープを持たないポリシーはすべてのプロジェクトに適用されるプログラムにコンパイルされるため、scope_regoは常にレスポンスに存在します。手書きのプログラムには構造化された形式がないため、Regoが直接作成された場合、policy_scopeはnullになります。

scope_dimensionsは、ポリシーが適用されるかどうかを判断するためにscope_regoが読み取る、compliance_frameworksやproject.idのようなドット区切りのコンテキストパスをリストします。GitLabはこのリストを導出するため、属性に送信する値は無視されます。この値は常に配列であり、ポリシーがスコープ外の場合には空ですが、policy_scopeからコンパイルされる代わりにscope_regoが直接作成された場合は除きます。その場合、GitLabは手書きのプログラムからパスを導出できないため、scope_dimensionsはnullとなり、パスが空ではなく不明であることを意味します。

ポリシースコープ構造

policy_scopeは1つ以上の基準を保持し、match_modeがそれらの組み合わせ方を制御します。基準は、整数として、またはidキーを持つオブジェクトとしてIDを指定します。GitLabはIDを重複排除してソートするため、作成順序によってコンパイルされたプログラムが変更されることはありません。

属性タイプ説明
applicationオブジェクトアプリケーションセキュリティ属性IDのincludingとexcludingリスト。
business_impactオブジェクトビジネス影響セキュリティ属性IDのincludingとexcludingリスト。
business_unitオブジェクトビジネスユニットセキュリティ属性IDのincludingとexcludingリスト。
compliance_frameworks配列プロジェクトが持つ必要のあるコンプライアンスフレームワークのID。includingとexcludingではなく、リストを直接受け取ります。
exposureオブジェクト露出セキュリティ属性IDのincludingとexcludingリスト。
groupsオブジェクトグループIDのincludingとexcludingリスト。
match_mode文字列allまたはanyのいずれか。allの場合、すべての基準が一致する必要があります。anyの場合、1つの一致で十分です。その他の値はallとして扱われます。
projectsオブジェクトプロジェクトIDのincludingとexcludingリスト。excludingは{"type": "personal"}と{"type": "archived"}も受け入れ、これらはその種類のすべてのプロジェクトを除外します。

例:

json
{
  "match_mode": "any",
  "compliance_frameworks": [{ "id": 5 }],
  "projects": { "including": [12, 34], "excluding": [{ "type": "archived" }] },
  "groups": { "including": [{ "id": 7 }] }
}

GitLabがIDとして読み取れない値は400 Bad Requestを返します。これは、数値でない値、および1から9223372036854775807の範囲外の数値に適用されます。

以下の3つのケースは受け入れられ、知っておく価値があります。なぜなら、それぞれが期待されるものとは異なる方法でポリシーをスコープ指定するためです:

  • includingリストでIDが指定されていない場合、その基準には何も一致しません。match_mode: allの場合、ポリシーはどのプロジェクトにも適用されません。match_mode: anyの場合、別の基準が依然として一致する可能性があります。
  • excludingリストでIDが指定されていない場合、何も除外されません。
  • GitLabが認識しない基準は効果がありません。それが唯一の基準であった場合、ポリシーはすべてのプロジェクトに適用されます。

ルールとアクション

rulesとactionsは配列です。各エントリには次の属性があります:

属性タイプ必須説明
type文字列はいルールの場合、すべてのルールタイプを一覧表示によって返されるIDのいずれか。アクションの場合、すべてのアクションを一覧表示によって返されるIDのいずれか。
value文字列またはハッシュいいえエントリが作用する対象。customルールはRegoソースを文字列として受け取ります。calendarまたはenvironmentルールはハッシュを受け取ります。すべてのアクションも同様です。

エントリを空白にすることはできません。空白のエントリは400 Bad Requestを返し、エラーは各空白の位置の名前を指定します（例: rules[0] is blank）。

各配列は最大5つのエントリを受け入れ、各エントリは4096バイトを超えてシリアル化することはできません。いずれかの制限を超えると400 Bad Requestが返されます。サイズ超過のエントリは、各違反位置の名前を指定します（例: rules has an entry exceeding maximum size of 4096 bytes at 0）。

リクエストは配列全体を置き換えます。単一のエントリを追加または削除することはできません。

Content-Type: application/jsonヘッダーとともに、rulesとactionsをJSONとして送信します。フォームエンコードされたボディは両方の配列を運ぶことができますが、一方のすべての値は文字列として到着するため、文字列ではないvalueはそのように表現することはできません。

レスポンス属性

ポリシーエンドポイントは次の属性を返します:

属性タイプ説明
actions配列ポリシーが実行するアクション。
created_at文字列ポリシーが作成された日付と時刻。
description文字列ポリシーの説明。
id整数ポリシーのID。
lifecycle_state文字列activeまたはdisabledのいずれか。
mode文字列audit、warn、enforceのいずれかです。
name文字列ポリシーの名前。
namespace_id整数ポリシーをオーナーとするグループのID。現在、常にnullとなります。これは、エンドポイントがnamespace_id属性を受け入れないため、このAPIを通じて作成されたすべてのポリシーはそれぞれの組織がオーナーとなるためです。
organization_id整数ポリシーが属する組織のID。
policy_rego文字列ポリシーのルールで、単一のRegoモジュールにコンパイルされます。ルールがないポリシーの場合はnull。
policy_scopeオブジェクトポリシーの構造化されたスコープ。Regoが直接作成された場合はnull。
rules配列ポリシーのルール。
scope_dimensions配列ポリシーが適用されるかどうかを判断するためにscope_regoが読み取るドット区切りのコンテキストパス。GitLabはこの値を導出するため、送信する値は無視されます。scope_regoが直接作成された場合はnull、それ以外の場合は配列、ポリシーがスコープ外の場合は空。
scope_rego文字列Regoとしてコンパイルされたポリシーのスコープ。
trigger_type文字列ポリシーが応答するトリガー。
updated_at文字列ポリシーが最後に変更された日付と時刻。
version整数ポリシーのリビジョン。少なくとも1つの値を変更する更新は、それを1つ増やします。

すべてのポリシーを一覧表示

組織に属するすべてのポリシーを一覧表示します。

GET /organizations/:id/security/policy_store

サポートされている属性は以下のとおりです:

属性タイプ必須説明
id整数はい組織のID。
page整数いいえ返す結果のページ。1がデフォルトです。
per_page整数いいえページあたりの結果数。デフォルトは20で、100を超える値はすべて100に制限されます。
trigger_type文字列いいえこのトリガーに応答するポリシーのみを返します。すべてのトリガーを一覧表示によって返されるIDのいずれか。

このエンドポイントはページ分けされた結果を返します。パフォーマンス上の理由により、組織が持つポリシーの数に関係なく、x-totalまたはx-total-pagesヘッダー、あるいはrel="last" linkは返されません。次のページがあるかどうかはx-next-pageを確認してください。

成功した場合、200とポリシー属性の配列を返します。

リクエスト例:

shell
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/organizations/1/security/policy_store?per_page=20"

レスポンス例:

json
[
  {
    "id": 1,
    "organization_id": 1,
    "namespace_id": null,
    "name": "Block deployments on critical findings",
    "description": null,
    "version": 1,
    "trigger_type": "deployment_requested",
    "rules": [{ "type": "custom", "value": "package governance" }],
    "policy_rego": "package governance\n",
    "actions": [{ "type": "block" }],
    "policy_scope": null,
    "scope_dimensions": [],
    "scope_rego": "package gitlab.scope\n\napplicable := [result.policy | some result in results; result.applies]\n...",
    "mode": "enforce",
    "lifecycle_state": "active",
    "created_at": "2026-08-07T13:56:32.985Z",
    "updated_at": "2026-08-07T13:56:32.985Z"
  }
]

ポリシーの取得

組織から単一のポリシーを取得します。

GET /organizations/:id/security/policy_store/:policy_id

サポートされている属性は以下のとおりです:

属性タイプ必須説明
id整数はい組織のID。
policy_id整数はいポリシーのID。

成功した場合、200とポリシー属性を返します。

リクエスト例:

shell
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/organizations/1/security/policy_store/1"

レスポンス例:

json
{
  "id": 1,
  "organization_id": 1,
  "namespace_id": null,
  "name": "Block deployments on critical findings",
  "description": null,
  "version": 1,
  "trigger_type": "deployment_requested",
  "rules": [{ "type": "custom", "value": "package governance" }],
  "policy_rego": "package governance\n",
  "actions": [{ "type": "block" }],
  "policy_scope": null,
  "scope_dimensions": [],
  "scope_rego": "package gitlab.scope\n\napplicable := [result.policy | some result in results; result.applies]\n...",
  "mode": "enforce",
  "lifecycle_state": "active",
  "created_at": "2026-08-07T13:56:32.985Z",
  "updated_at": "2026-08-07T13:56:32.985Z"
}

ポリシーの作成

組織にポリシーを作成します。

POST /organizations/:id/security/policy_store

サポートされている属性は以下のとおりです:

属性タイプ必須説明
id整数はい組織のID。
name文字列はいポリシーの名前。最大255文字。組織内で一意である必要があります。
rules配列はいポリシーのルール。少なくとも1つのエントリが必要で、最大5つまで。各エントリは最大4096バイトにシリアル化される必要があります。エントリが65536バイトを超えるRegoモジュールにコンパイルされると拒否されます。そのモジュールはpolicy_regoとして返されます。
trigger_type文字列はいポリシーが応答するトリガー。すべてのトリガーを一覧表示によって返されるIDのいずれか。
actions配列いいえポリシーが実行するアクション。最大5つのエントリ。各エントリは最大4096バイトにシリアル化される必要があります。
description文字列いいえポリシーの説明。最大4096文字。
lifecycle_state文字列いいえactiveまたはdisabledのいずれか。activeがデフォルトです。
mode文字列いいえaudit、warn、enforceのいずれかです。enforceがデフォルトです。
policy_scopeオブジェクトいいえポリシーの構造化されたスコープ。空でないscope_regoと組み合わせることはできません。Regoの4096文字を超えてコンパイルされると拒否されます。
scope_rego文字列いいえRegoとして作成されたポリシーのスコープ。最大4096文字。空でない値をpolicy_scopeと組み合わせることはできません。

成功した場合、201とポリシー属性を返します。次の条件で400 Bad Requestが返されます:

  • 属性が無効です。
  • 両方のスコープ形式が指定されています。
  • その名前はすでに組織内で使用されています。
  • コンパイルされたscope_regoが4096文字を超えています。
  • rulesが65536バイトを超えるRegoにコンパイルされます。
  • rulesまたはactionsが5つ以上のエントリを保持しています。
  • rulesまたはactionsのエントリが4096バイトを超えてシリアル化されます。

リクエスト例:

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Block deployments on critical findings",
    "trigger_type": "deployment_requested",
    "rules": [{ "type": "custom", "value": "package governance" }],
    "actions": [{ "type": "block" }],
    "policy_scope": { "compliance_frameworks": [{ "id": 5 }] }
  }' \
  --url "https://gitlab.example.com/api/v4/organizations/1/security/policy_store"

レスポンス例:

json
{
  "id": 1,
  "organization_id": 1,
  "namespace_id": null,
  "name": "Block deployments on critical findings",
  "description": null,
  "version": 1,
  "trigger_type": "deployment_requested",
  "rules": [{ "type": "custom", "value": "package governance" }],
  "policy_rego": "package governance\n",
  "actions": [{ "type": "block" }],
  "policy_scope": { "compliance_frameworks": [{ "id": 5 }] },
  "scope_dimensions": ["compliance_frameworks"],
  "scope_rego": "package gitlab.scope\n\napplicable := [result.policy | some result in results; result.applies]\n...",
  "mode": "enforce",
  "lifecycle_state": "active",
  "created_at": "2026-08-07T13:56:32.985Z",
  "updated_at": "2026-08-07T13:56:32.985Z"
}

ポリシーの更新

組織内のポリシーを更新します。パスパラメータ以外のすべての属性はオプションですが、リクエストは少なくとも1つ指定する必要があります。送信されなかった属性はそのまま残り、少なくとも1つの値を変更する更新はversionを1つ増やします。保存されている値を再指定するリクエストは何も変更せず、versionはそのまま残ります。

PATCH /organizations/:id/security/policy_store/:policy_id

サポートされている属性は以下のとおりです:

属性タイプ必須説明
id整数はい組織のID。
policy_id整数はいポリシーのID。
actions配列いいえポリシーが実行するアクション。保存されているアクションを置き換え、最大5つのエントリ。各エントリは最大4096バイトにシリアル化される必要があります。
description文字列いいえポリシーの説明。最大4096文字。
lifecycle_state文字列いいえactiveまたはdisabledのいずれか。
mode文字列いいえaudit、warn、enforceのいずれかです。
name文字列いいえポリシーの名前。最大255文字。組織内で一意である必要があります。
policy_scopeオブジェクトいいえポリシーの構造化されたスコープ。空でないscope_regoと組み合わせることはできません。Regoの4096文字を超えてコンパイルされると拒否されます。
rules配列いいえポリシーのルール。保存されているルールを置き換え、最大5つのエントリ。各エントリは最大4096バイトにシリアル化される必要があります。エントリが65536バイトを超えるRegoモジュールにコンパイルされると拒否されます。そのモジュールはpolicy_regoとして返されます。
scope_rego文字列いいえRegoとして作成されたポリシーのスコープ。最大4096文字。作成されたプログラムを廃止し、policy_scopeから再コンパイルするには、空の値を送信します。
trigger_type文字列いいえポリシーが応答するトリガー。すべてのトリガーを一覧表示によって返されるIDのいずれか。

ポリシーの名前を変更すると、ポリシー名が生成されたプログラムに表示されるため、GitLabは生成されたscope_regoを再コンパイルする必要があります。直接作成されたscope_regoはそのまま残されます。

成功した場合、200とポリシー属性を返します。次の条件で400 Bad Requestが返されます:

  • 変更する属性が指定されていません。
  • 属性が無効です。
  • 両方のスコープ形式が指定されています。
  • 新しい名前はすでに組織内で使用されています。
  • 再コンパイルされたscope_regoが4096文字を超えています。
  • 置き換えられるrulesが65536バイトを超えるRegoにコンパイルされます。
  • 置き換えられるrulesまたはactionsが5つ以上のエントリを保持しています。
  • 置き換えられるrulesまたはactionsのエントリが4096バイトを超えてシリアル化されます。

リクエスト例:

shell
curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
  --data-urlencode "name=Renamed policy" \
  --url "https://gitlab.example.com/api/v4/organizations/1/security/policy_store/1"

レスポンス例:

json
{
  "id": 1,
  "organization_id": 1,
  "namespace_id": null,
  "name": "Renamed policy",
  "description": null,
  "version": 2,
  "trigger_type": "deployment_requested",
  "rules": [{ "type": "custom", "value": "package governance" }],
  "policy_rego": "package governance\n",
  "actions": [{ "type": "block" }],
  "policy_scope": null,
  "scope_dimensions": [],
  "scope_rego": "package gitlab.scope\n\napplicable := [result.policy | some result in results; result.applies]\n...",
  "mode": "enforce",
  "lifecycle_state": "active",
  "created_at": "2026-08-07T13:56:32.985Z",
  "updated_at": "2026-08-07T14:02:47.198Z"
}

ポリシーの削除

組織からポリシーを削除します。

DELETE /organizations/:id/security/policy_store/:policy_id

サポートされている属性は以下のとおりです:

属性タイプ必須説明
id整数はい組織のID。
policy_id整数はいポリシーのID。

成功した場合、204と空のレスポンスボディを返します。

リクエスト例:

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/organizations/1/security/policy_store/1"