Policy store API

Use this API to author security policies in the policy store. A policy belongs to an organization, responds to a single trigger, and carries the rules and actions that make up its behavior.

These endpoints are available only when both of the following are true:

• The security_policies_v2 feature flag is enabled.
• An administrator has enabled the policy store experiment for the instance in Admin > Settings > Security and compliance.

When either is not true, the endpoints return 404 Not Found. When the instance is not licensed for security orchestration policies, they return 403 Forbidden.

Catalogs

The catalog endpoints describe what a policy can be built from. They return the same static content for every caller, so they take no authentication and no permission.

List all triggers

List all triggers a policy can respond to.

GET /security/policy_store/triggers

If successful, returns 200 and the following response attributes:

Example request:

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

Example response:

[
  { "id": "deployment_requested", "name": "Deployment" }
]

List all actions

List all actions a policy can take.

GET /security/policy_store/actions

If successful, returns 200 and the following response attributes:

Example request:

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

Example response:

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

List all rule kinds

List all rule kinds a policy can be built from.

GET /security/policy_store/rules

If successful, returns 200 and the following response attributes:

Example request:

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

Example response:

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

Policies

Every call to a policy endpoint must be authenticated, and the caller must be an owner of the organization or an instance administrator. A caller who cannot administer the organization receives 403 Forbidden, and one who cannot see the organization at all receives 404 Not Found.

A policy that belongs to another organization is indistinguishable from one that does not exist. An ID cannot be used to read or change a policy across organizations.

Policy scope

A policy applies everywhere unless it carries a scope. A scope is authored one of two ways, and a request may use one or the other but not both:

• policy_scope: structured data that GitLab compiles into scope_rego.
• scope_rego: a Rego program supplied directly, stored as authored.

A request that supplies both returns 400 Bad Request. An empty scope_rego does not count as the second form, so either operation accepts it alongside policy_scope. On Create a policy, an empty value has the same effect as omitting it. On Update a policy, it retires an authored program and compiles a new one from policy_scope.

scope_rego is always present in a response, because a policy with no scope compiles to a program that applies to every project. policy_scope is null when the Rego was authored directly, because a hand-written program has no structured form.

Policy scope structure

policy_scope holds one or more criteria, and match_mode controls how they combine. A criterion names IDs, either as integers or as objects with an id key. GitLab deduplicates and sorts the IDs, so authoring order does not change the compiled program.

For example:

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

A value GitLab cannot read as an ID returns 400 Bad Request. That covers a value that is not a number, and a number outside the range 1 to 9223372036854775807.

Three cases are accepted and worth knowing, because each one scopes the policy differently from what you might expect:

• An including list that names no IDs matches nothing for that criterion. Under match_mode: all the policy then applies to no project. Under match_mode: any another criterion can still match.
• An excluding list that names no IDs excludes nothing.
• A criterion GitLab does not recognize has no effect. If it was the only criterion supplied, the policy applies to every project.

Rules and actions

rules and actions are arrays. Each entry has the following attributes:

An entry cannot be blank. A blank entry returns 400 Bad Request, and the error names each blank position, for example rules[0] is blank.

A request replaces the whole array. You cannot add or remove a single entry.

Send rules and actions as JSON with a Content-Type: application/json header. A form-encoded body can carry both arrays, but every value in one arrives as a string, so a value that is not a string cannot be expressed that way.

Response attributes

The policy endpoints return the following attributes:

List all policies

List all policies belonging to an organization.

GET /organizations/:id/security/policy_store

Supported attributes:

If successful, returns 200 and an array of policy attributes.

Example request:

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

Example response:

[
  {
    "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_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"
  }
]

Retrieve a policy

Retrieve a single policy from an organization.

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

Supported attributes:

If successful, returns 200 and the policy attributes.

Example request:

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

Example response:

{
  "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_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"
}

Create a policy

Create a policy in an organization.

POST /organizations/:id/security/policy_store

Supported attributes:

If successful, returns 201 and the policy attributes. Returns 400 Bad Request when an attribute is invalid, both scope forms are supplied, or the name is already taken in the organization.

Example request:

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"

Example response:

{
  "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_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"
}

Update a policy

Update a policy in an organization. Every attribute other than the path parameters is optional, but a request must name at least one. Attributes that are not sent are left as they are, and an update that changes at least one value raises version by one. A request that restates the stored values changes nothing, and leaves version as it is.

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

Supported attributes:

When you rename a policy, GitLab must recompile a generated scope_rego, because the policy name appears in the generated program. A scope_rego that was authored directly is left as it is.

If successful, returns 200 and the policy attributes. Returns 400 Bad Request when an attribute is invalid, both scope forms are supplied, the new name is already taken in the organization, or a recompiled scope_rego exceeds 4096 characters.

Example request:

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"

Example response:

{
  "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_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 a policy

Delete a policy from an organization.

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

Supported attributes:

If successful, returns 204 and an empty response body.

Example request:

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