정책 저장소 API
GitLab v19.6Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
요약
이 기능의 가용성은 기능 플래그에 의해 제어됩니다. 이 API를 사용하여 정책 저장소에서 보안 정책을 작성합니다. 이 엔드포인트는 다음 조건을 모두 충족할 때만 사용할 수 있습니다. 기능 플래그, 인스턴스 설정 또는 조직의 참여 선택 중 하나라도 충족되지 않으면 엔드포인트는 404 Not Found를 반환합니다.
히스토리
- GitLab 19.3에서
security_policies_v2라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다. 이 기능은 실험입니다. - 카탈로그 엔드포인트:
- GitLab 19.4에서 인증을 요구하도록 변경되었습니다.
environment_advanced및deployment_promoted트리거가 GitLab 19.4에서 도입되었습니다.set_setting액션이 GitLab 19.6에서 도입되었습니다.project.before_settings_update,project.after_create,project.after_transfer트리거와[].kind트리거 속성이 GitLab 19.6에서 도입되었습니다.- 정책 엔드포인트:
- GitLab 19.4에서 정책을 데이터베이스에 저장하도록 변경되었습니다.
policy_rego응답 속성이 GitLab 19.4에서 도입되었습니다.scope_dimensions응답 속성이 GitLab 19.4에서 도입되었습니다.lifecycle_state필터가 GitLab 19.4에서 도입되었습니다.- 정책 생성 및 업데이트 엔드포인트:
rules및actions에 대한 제한이 GitLab 19.4에서 도입되었습니다.- Rego 검증이 GitLab 19.5에서 도입되었습니다.
- 그룹 엔드포인트가 GitLab 19.5에서 도입되었습니다.
이 기능의 가용성은 기능 플래그에 의해 제어됩니다. 자세한 내용은 기록을 참조합니다. 이 기능은 테스트에 사용할 수 있지만 프로덕션 환경에서 사용할 준비는 되지 않았습니다.
이 API를 사용하여 정책 저장소에서 보안 정책을 작성합니다. 정책은 조직에 속하며 하나의 트리거에 반응하고, 동작을 구성하는 규칙과 액션을 가집니다.
이 엔드포인트는 다음 조건을 모두 충족할 때만 사용할 수 있습니다.
security_policies_v2기능 플래그가 활성화되어 있습니다.- 관리자가 Admin > Settings > Security and compliance에서 인스턴스의 정책 저장소 실험을 활성화했습니다.
- 조직 엔드포인트의 경우 해당 조직이 참여를 선택했습니다.
- 그룹 엔드포인트의 경우 최상위 그룹이 참여를 선택했습니다.
기능 플래그, 인스턴스 설정 또는 조직의 참여 선택 중 하나라도 충족되지 않으면
엔드포인트는 404 Not Found를 반환합니다.
인스턴스에 보안 오케스트레이션 정책 라이선스가 없거나 그룹이 참여를 선택하지 않은 경우에는
403 Forbidden을 반환합니다.
카탈로그#
카탈로그 엔드포인트는 정책을 구성할 수 있는 요소를 설명하며, 자격이 있는 모든 호출자에게 동일한 정적 콘텐츠를 반환합니다.
호출자는 소속 조직에서 security_policies_v2 기능 플래그가 활성화된 인증된 사용자여야 합니다.
이 조건을 충족하지 않으면 엔드포인트는 404 Not Found를 반환합니다.
모든 트리거 목록 조회#
정책이 반응할 수 있는 모든 트리거를 나열합니다.
GET /security/policy_store/triggers
성공하면 200 OK와 다음 응답 속성을
반환합니다.
| 속성 | 유형 | 설명 |
|---|---|---|
[].id |
string | 트리거의 ID이며, 정책을 작성할 때 trigger_type으로 사용합니다. |
[].name |
string | 트리거의 표시 이름입니다. |
[].kind |
string | gate 또는 event입니다. gate 트리거는 변경 전에 평가되며 변경을 중단시킬 수 있습니다. event 트리거는 변경 후에 평가되며 변경을 중단시킬 수 없습니다. |
요청 예시:
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/security/policy_store/triggers"
응답 예시:
[
{ "id": "deployment_requested", "name": "Deployment requested", "kind": "gate" },
{ "id": "environment_advanced", "name": "Environment advanced", "kind": "gate" },
{ "id": "deployment_promoted", "name": "Deployment promoted", "kind": "gate" },
{ "id": "project.before_settings_update", "name": "Project settings change requested", "kind": "gate" },
{ "id": "project.after_create", "name": "Project created", "kind": "event" },
{ "id": "project.after_transfer", "name": "Project transferred", "kind": "event" }
]
모든 액션 목록 조회#
정책이 수행할 수 있는 모든 액션을 나열합니다.
GET /security/policy_store/actions
성공하면 200 OK와 다음 응답 속성을
반환합니다.
| 속성 | 유형 | 설명 |
|---|---|---|
[].id |
string | 액션의 ID입니다. |
[].name |
string | 액션의 표시 이름입니다. |
요청 예시:
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/security/policy_store/actions"
응답 예시:
[
{ "id": "block", "name": "Block" },
{ "id": "require_approval", "name": "Require approval" },
{ "id": "set_setting", "name": "Set project setting" },
{ "id": "log_audit_trail", "name": "Log audit trail" }
]
모든 규칙 종류 목록 조회#
정책을 구성할 수 있는 모든 규칙 종류를 나열합니다.
GET /security/policy_store/rules
성공하면 200 OK와 다음 응답 속성을
반환합니다.
| 속성 | 유형 | 설명 |
|---|---|---|
[].id |
string | 규칙 종류의 ID입니다. |
[].name |
string | 규칙 종류의 표시 이름입니다. |
요청 예시:
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/security/policy_store/rules"
응답 예시:
[
{ "id": "custom", "name": "Custom" },
{ "id": "calendar", "name": "Calendar" },
{ "id": "environment", "name": "Environment" },
{ "id": "setting_validation", "name": "Project setting validation" }
]
정책 속성#
조직 및 그룹 정책 엔드포인트는 동일한 정책 범위, 규칙, 액션, 응답 속성을 사용합니다.
정책 범위 속성#
policy_scope는 하나 이상의 기준을 담고, match_mode는 이 기준을 결합하는 방식을 제어합니다.
기준은 정수 또는 id 키를 가진 객체로 ID를 지정합니다.
GitLab은 ID의 중복을 제거하고 정렬하므로, 작성 순서가 컴파일된 프로그램에 영향을 주지 않습니다.
| 속성 | 유형 | 설명 |
|---|---|---|
application |
object | 애플리케이션 보안 속성 ID의 including 및 excluding 목록입니다. |
business_impact |
object | 비즈니스 영향 보안 속성 ID의 including 및 excluding 목록입니다. |
business_unit |
object | 사업부 보안 속성 ID의 including 및 excluding 목록입니다. |
compliance_frameworks |
array | 프로젝트가 가져야 하는 컴플라이언스 프레임워크의 ID입니다. including 및 excluding 대신 목록을 직접 받습니다. |
exposure |
object | 노출 보안 속성 ID의 including 및 excluding 목록입니다. |
groups |
object | 그룹 ID의 including 및 excluding 목록입니다. |
match_mode |
string | all 또는 any입니다. all이면 모든 기준이 일치해야 합니다. any이면 하나만 일치해도 됩니다. 다른 값은 all로 처리됩니다. |
projects |
object | 프로젝트 ID의 including 및 excluding 목록입니다. excluding은 {"type": "personal"}과 {"type": "archived"}도 받으며, 해당 종류의 모든 프로젝트를 제외합니다. |
예시:
{
"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 범위를 벗어난 숫자가 여기에 해당합니다.
다음 세 경우는 허용되지만, 각각 예상과 다르게 정책 범위가 지정되므로 알아 둘 필요가 있습니다.
- ID를 지정하지 않은
including목록은 해당 기준에서 아무것도 일치시키지 않습니다.match_mode: all에서는 정책이 어떤 프로젝트에도 적용되지 않습니다.match_mode: any에서는 다른 기준이 여전히 일치할 수 있습니다. - ID를 지정하지 않은
excluding목록은 아무것도 제외하지 않습니다. - GitLab이 인식하지 못하는 기준은 아무 효과가 없습니다. 이 기준이 제공된 유일한 기준이면 정책은 모든 프로젝트에 적용됩니다.
규칙 및 액션 속성#
rules와 actions는 배열입니다.
각 항목에는 다음 속성이 있습니다.
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
type |
string | 예 | 규칙의 경우 모든 규칙 종류 목록 조회에서 반환되는 ID 중 하나입니다. 액션의 경우 모든 액션 목록 조회에서 반환되는 ID 중 하나입니다. |
value |
string 또는 hash | 아니요 | 항목이 작용하는 대상입니다. custom 규칙은 Rego 소스를 문자열로 받습니다. 그 외 모든 규칙과 모든 액션은 해시를 받습니다. setting_validation 규칙은 평가 컨텍스트에 지정된 설정이 없는 프로젝트에서는 위반을 보고하지 않습니다. |
각 배열은 최대 5개 항목을 받으며, 각 항목은 직렬화했을 때 최대 4096바이트여야 합니다.
크기를 초과한 항목에 대한 오류는 각 위치를 알려 줍니다. 예를 들면
rules has an entry exceeding maximum size of 4096 bytes at 0입니다.
항목은 비어 있을 수 없습니다.
빈 항목은 400 Bad Request를 반환하며, 오류는 비어 있는 각 위치를 알려 줍니다.
예를 들면 rules[0] is blank입니다.
custom 규칙의 Rego와 모든 규칙이 병합되는 policy_rego 모듈은 구문 분석이 가능해야 합니다.
그렇지 않은 custom 규칙은 400 Bad Request를 반환합니다. 오류는 규칙의 위치를 알려 주고,
value로 보낸 Rego의 행과 열을 포함한 엔진 메시지를 담습니다.
예를 들면 rules[0] is invalid: error: expecting `}` while parsing object (at line:column)입니다.
policy_rego 모듈도 모든 규칙이 병합된 뒤 구문 분석합니다. 모든 규칙이
이미 개별적으로 구문 분석을 통과했으므로, 이 단계의 실패는 정책 엔진의
결함으로 처리됩니다. 요청은 500 Internal Server Error를 반환하고,
정책은 저장되지 않으며, 결함은 오류 추적에 보고됩니다.
rules와 actions는 Content-Type: application/json 헤더와 함께 JSON으로 보냅니다.
폼 인코딩 본문도 두 배열을 모두 담을 수 있지만, 한 배열의 모든 값이 문자열로 전달되므로
문자열이 아닌 value는 그 방식으로 표현할 수 없습니다.
응답 속성#
정책 엔드포인트는 다음 속성을 반환합니다.
| 속성 | 유형 | 설명 |
|---|---|---|
actions |
array | 정책이 수행하는 액션입니다. |
created_at |
string | 정책을 생성한 날짜와 시간입니다. |
description |
string | 정책에 대한 설명입니다. |
id |
integer | 정책의 ID입니다. |
lifecycle_state |
string | active 또는 disabled입니다. |
mode |
string | audit, warn, enforce 중 하나입니다. |
name |
string | 정책의 이름입니다. |
namespace_id |
integer | 정책을 소유한 그룹의 ID입니다. 조직 엔드포인트로 생성한 정책은 조직이 소유하므로 null이며, 그룹을 볼 수 없는 경우에도 null입니다. |
organization_id |
integer | 정책이 속한 조직의 ID입니다. |
policy_rego |
string | 정책의 규칙을 하나의 Rego 모듈로 컴파일한 것입니다. 규칙이 없는 정책은 null입니다. |
policy_scope |
object | 정책의 구조화된 범위입니다. Rego를 직접 작성한 경우에는 null입니다. |
rules |
array | 정책의 규칙입니다. |
scope_dimensions |
array | scope_rego가 정책 적용 여부를 판단하기 위해 읽는 점 표기 컨텍스트 경로입니다. GitLab이 이 값을 도출하므로, 보낸 값은 무시합니다. scope_rego를 직접 작성한 경우에는 null이고, 그 외에는 배열이며 정책에 범위가 없으면 비어 있습니다. |
scope_rego |
string | Open Policy Agent의 정책 언어인 Rego 프로그램으로 표현한 정책의 범위입니다. 직접 작성하거나 policy_scope에서 컴파일됩니다. 범위가 없는 정책은 모든 프로젝트에 적용되는 프로그램으로 컴파일되므로 항상 존재합니다. |
trigger_type |
string | 정책이 반응하는 트리거입니다. |
updated_at |
string | 정책을 마지막으로 변경한 날짜와 시간입니다. |
version |
integer | 정책의 리비전입니다. 값이 하나라도 바뀌는 업데이트는 이 값을 1씩 올립니다. |
조직 정책#
조직 엔드포인트를 사용하여 조직의 정책을 관리합니다.
사전 요구 사항:
- 조직의 소유자이거나 인스턴스의 관리자여야 합니다.
조직의 참여를 선택하려면 policyStoreExperimentEnabled를 true로 설정하여
organizationUpdate GraphQL 뮤테이션을 보냅니다.
실험을 조직에서 사용할 수 없으면 뮤테이션은 오류를 반환합니다.
정책 엔드포인트를 호출할 때마다 인증해야 합니다.
조직을 관리할 수 없는 호출자는 403 Forbidden을 받고, 조직을 전혀 볼 수 없는 호출자는
404 Not Found를 받습니다.
다른 조직에 속한 정책은 존재하지 않는 정책과 구별되지 않습니다. ID로 조직 간에 정책을 읽거나 변경할 수 없습니다.
모든 조직 정책 목록 조회#
조직에 속한 모든 정책을 나열합니다.
GET /organizations/:id/security/policy_store
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer | 예 | 조직의 ID입니다. |
lifecycle_state |
string | 아니요 | active 정책만, disabled 정책만 또는 all 정책을 반환합니다. 기본값은 active입니다. |
namespace_ids |
array | 아니요 | 네임스페이스의 ID이며, 보통 그룹과 그 상위 그룹입니다. 해당 네임스페이스의 정책과 조직 전체 정책만 반환합니다. 고유 ID는 최대 21개이며, 이를 초과하면 400 Bad Request를 반환합니다. GitLab.com에서 기본 조직은 조직 전체 정책을 반환하지 않으며, 이 값 없이는 어떤 정책도 반환하지 않습니다. |
page |
integer | 아니요 | 반환할 결과의 페이지입니다. 기본값은 1입니다. |
per_page |
integer | 아니요 | 페이지당 결과 수입니다. 기본값은 20이며, 100을 초과하는 값은 100으로 제한됩니다. |
trigger_type |
string | 아니요 | 이 트리거에 반응하는 정책만 반환합니다. 모든 트리거 목록 조회에서 반환되는 ID 중 하나입니다. |
이 엔드포인트는 페이지네이션된 결과를 반환합니다.
성능상의 이유로, 조직에 정책이 몇 개 있든 x-total 또는 x-total-pages 헤더와
rel="last" link를 반환하지 않습니다. 다음 페이지가 있는지 알려면
x-next-page를 확인합니다.
성공하면 200 OK와
정책 속성의 배열을 반환합니다.
GitLab.com에서 namespace_ids 없이 기본 조직에 요청할 때 trigger_type이
project.before_settings_update, project.after_create, project.after_transfer이면
이 트리거는 그룹 계층 구조를 담고 있으므로 400 Bad Request를 반환합니다.
요청 예시:
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/organizations/1/security/policy_store?per_page=20"
응답 예시:
[
{
"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 |
integer | 예 | 조직의 ID입니다. |
policy_id |
integer | 예 | 정책의 ID입니다. |
성공하면 200 OK와
정책 속성을 반환합니다.
GitLab.com에서 기본 조직은 모든 정책에 대해 404 Not Found를 반환합니다. 각 고객은
자신의 그룹을 통해 정책에 접근합니다.
요청 예시:
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/organizations/1/security/policy_store/1"
응답 예시:
{
"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 |
integer | 예 | 조직의 ID입니다. |
name |
string | 예 | 정책의 이름입니다. 최대 255자입니다. 조직 내에서 고유해야 합니다. |
rules |
array | 예 | 정책의 규칙입니다. 항목 속성은 규칙 및 액션 속성을 참조합니다. 항목이 하나 이상 필요하며 최대 5개입니다. 각 항목은 직렬화했을 때 최대 4096바이트여야 합니다. 항목이 65536바이트보다 큰 Rego 모듈로 컴파일되면 거부됩니다. 이 모듈은 policy_rego로 반환됩니다. |
trigger_type |
string | 예 | 정책이 반응하는 트리거입니다. 모든 트리거 목록 조회에서 반환되는 ID 중 하나입니다. |
actions |
array | 아니요 | 정책이 수행하는 액션입니다. 항목 속성은 규칙 및 액션 속성을 참조합니다. 최대 5개 항목입니다. 각 항목은 직렬화했을 때 최대 4096바이트여야 합니다. |
description |
string | 아니요 | 정책에 대한 설명입니다. 최대 4096자입니다. |
lifecycle_state |
string | 아니요 | active 또는 disabled입니다. 기본값은 active입니다. |
mode |
string | 아니요 | audit, warn, enforce 중 하나입니다. 기본값은 warn입니다. |
policy_scope |
object | 아니요 | GitLab이 scope_rego로 컴파일하는 정책의 구조화된 범위입니다. 속성은 정책 범위 속성을 참조합니다. 비어 있지 않은 scope_rego와 함께 사용할 수 없습니다. 4096자를 초과하는 Rego로 컴파일되면 거부됩니다. |
scope_rego |
string | 아니요 | Rego 프로그램으로 직접 작성한 정책의 범위입니다. GitLab은 작성한 그대로 저장합니다. 최대 4096자입니다. 비어 있지 않은 값은 policy_scope와 함께 사용할 수 없습니다. 빈 값은 생략한 것과 효과가 같습니다. Rego로 구문 분석되지 않는 값은 400 Bad Request를 반환합니다. |
성공하면 201 Created와
정책 속성을 반환합니다.
다음 조건에서는 400 Bad Request를 반환합니다.
- 속성이 유효하지 않습니다.
- 두 가지 범위 형식이 모두 제공되었습니다.
- 조직에서 이미 사용 중인 이름입니다.
- 컴파일된
scope_rego가 4096자를 초과합니다. rules가 65536바이트를 초과하는 Rego로 컴파일됩니다.rules또는actions에 항목이 5개를 초과합니다.rules또는actions의 항목이 직렬화했을 때 4096바이트를 초과합니다.
GitLab.com에서 기본 조직에 정책을 생성하면
422 Unprocessable Entity를 반환합니다. 자체 조직이 없는 그룹은
기본 조직을 공유하므로, 그곳의 조직 전체 정책은 모든 그룹에 적용됩니다.
대신 그룹에 정책을 생성합니다.
요청 예시:
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"
응답 예시:
{
"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": "warn",
"lifecycle_state": "active",
"created_at": "2026-08-07T13:56:32.985Z",
"updated_at": "2026-08-07T13:56:32.985Z"
}
조직 정책 업데이트#
조직의 정책을 업데이트합니다.
경로 매개변수 외의 모든 속성은 선택 사항이지만, 요청은 하나 이상을 지정해야 합니다.
보내지 않은 속성은 그대로 유지되며, 값이 하나라도 바뀌는 업데이트는 version을 1 올립니다.
저장된 값을 그대로 다시 보내는 요청은 아무것도 변경하지 않으며 version도 그대로 둡니다.
PATCH /organizations/:id/security/policy_store/:policy_id
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer | 예 | 조직의 ID입니다. |
policy_id |
integer | 예 | 정책의 ID입니다. |
actions |
array | 아니요 | 정책이 수행하는 액션입니다. 항목 속성은 규칙 및 액션 속성을 참조합니다. 저장된 액션을 대체하며, 최대 5개 항목입니다. 각 항목은 직렬화했을 때 최대 4096바이트여야 합니다. |
description |
string | 아니요 | 정책에 대한 설명입니다. 최대 4096자입니다. |
lifecycle_state |
string | 아니요 | active 또는 disabled입니다. |
mode |
string | 아니요 | audit, warn, enforce 중 하나입니다. |
name |
string | 아니요 | 정책의 이름입니다. 최대 255자입니다. 조직 내에서 고유해야 합니다. |
policy_scope |
object | 아니요 | GitLab이 scope_rego로 컴파일하는 정책의 구조화된 범위입니다. 속성은 정책 범위 속성을 참조합니다. 비어 있지 않은 scope_rego와 함께 사용할 수 없습니다. 4096자를 초과하는 Rego로 컴파일되면 거부됩니다. |
rules |
array | 아니요 | 정책의 규칙입니다. 항목 속성은 규칙 및 액션 속성을 참조합니다. 저장된 규칙을 대체하며, 최대 5개 항목입니다. 각 항목은 직렬화했을 때 최대 4096바이트여야 합니다. 항목이 65536바이트보다 큰 Rego 모듈로 컴파일되면 거부됩니다. 이 모듈은 policy_rego로 반환됩니다. |
scope_rego |
string | 아니요 | Rego 프로그램으로 직접 작성한 정책의 범위입니다. GitLab은 작성한 그대로 저장합니다. 최대 4096자입니다. 직접 작성한 프로그램을 폐기하고 policy_scope에서 다시 컴파일하려면 빈 값을 보냅니다. Rego로 구문 분석되지 않는 값은 400 Bad Request를 반환합니다. |
trigger_type |
string | 아니요 | 정책이 반응하는 트리거입니다. 모든 트리거 목록 조회에서 반환되는 ID 중 하나입니다. 그룹에 속한 정책은 project.before_settings_update, project.after_create, project.after_transfer 중 하나여야 합니다. 이 트리거만 그룹 계층 구조를 담고 있기 때문입니다. |
정책의 이름을 바꾸면 생성된 프로그램에 정책 이름이 들어 있으므로,
GitLab은 생성된 scope_rego를 다시 컴파일해야 합니다.
직접 작성한 scope_rego는 그대로 유지됩니다.
성공하면 200 OK와
정책 속성을 반환합니다.
GitLab.com에서 기본 조직은 요청이 유효해도 모든 정책에 대해 404 Not Found를 반환합니다.
각 고객은 자신의 그룹을 통해 정책에 접근합니다.
다음 조건에서는 400 Bad Request를 반환합니다.
- 변경할 속성이 지정되지 않았습니다.
- 속성이 유효하지 않습니다.
- 두 가지 범위 형식이 모두 제공되었습니다.
- 새 이름이 조직에서 이미 사용 중입니다.
- 다시 컴파일된
scope_rego가 4096자를 초과합니다. - 대체할
rules가 65536바이트를 초과하는 Rego로 컴파일됩니다. - 대체할
rules또는actions에 항목이 5개를 초과합니다. - 대체할
rules또는actions의 항목이 직렬화했을 때 4096바이트를 초과합니다. - 정책이 그룹에 속하는데 새
trigger_type이 그룹 정책에서 사용할 수 없는 값입니다.
요청 예시:
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"
응답 예시:
{
"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 |
integer | 예 | 조직의 ID입니다. |
policy_id |
integer | 예 | 정책의 ID입니다. |
성공하면 204 No Content를 반환합니다.
GitLab.com에서 기본 조직은 모든 정책에 대해 404 Not Found를 반환합니다. 각 고객은
자신의 그룹을 통해 정책에 접근합니다.
요청 예시:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/organizations/1/security/policy_store/1"
그룹 정책#
그룹 엔드포인트를 사용하여 그룹의 정책을 관리합니다.
이 엔드포인트에서 id는 그룹의 ID 또는 URL 인코딩된 경로입니다.
사전 요구 사항:
- 그룹이 정책 저장소 실험의 참여를 선택해야 합니다. 하위 그룹은 최상위 그룹의 참여 선택을 따릅니다.
- 정책을 나열하거나 조회하려면 그룹의 Owner 권한이 있거나, 감사자이거나, 인스턴스의 관리자여야 합니다.
- 정책을 생성, 업데이트 또는 삭제하려면 그룹의 Owner 권한이 있거나 인스턴스의 관리자여야 합니다.
그룹은 policy_store_experiment_enabled 설정으로 참여를 선택합니다.
보안 정책 프로젝트를 통해 이미 보안 정책을 구성한 그룹은 참여를 선택할 수 없습니다.
A group that already has security policies configured through a security policy project cannot opt in.
모든 그룹 정책 목록 조회#
그룹에 속한 모든 정책을 나열합니다.
GET /groups/:id/security/policy_store
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer 또는 string | 예 | 그룹의 ID 또는 URL 인코딩된 경로입니다. |
lifecycle_state |
string | 아니요 | active 정책만, disabled 정책만 또는 all 정책을 반환합니다. 기본값은 active입니다. |
page |
integer | 아니요 | 반환할 결과의 페이지입니다. 기본값은 1입니다. |
per_page |
integer | 아니요 | 페이지당 결과 수입니다. 기본값은 20이며, 100을 초과하는 값은 100으로 제한됩니다. |
trigger_type |
string | 아니요 | 이 트리거에 반응하는 정책만 반환합니다. 모든 트리거 목록 조회에서 반환되는 ID 중 하나입니다. |
이 엔드포인트는 페이지네이션된 결과를 반환합니다. 성능상의 이유로, 그룹에 정책이 몇 개
있든 x-total 또는 x-total-pages 헤더와 rel="last" link를 반환하지 않습니다.
다음 페이지가 있는지 알려면 x-next-page를 확인합니다.
성공하면 200 OK와
정책 속성의 배열을 반환합니다.
요청 예시:
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/5/security/policy_store?per_page=20"
응답 예시:
[
{
"id": 1,
"organization_id": 1,
"namespace_id": 5,
"name": "Block settings changes on critical findings",
"description": null,
"version": 1,
"trigger_type": "project.before_settings_update",
"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 /groups/:id/security/policy_store/:policy_id
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer 또는 string | 예 | 그룹의 ID 또는 URL 인코딩된 경로입니다. |
policy_id |
integer | 예 | 정책의 ID입니다. |
요청 예시:
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/5/security/policy_store/1"
응답 예시:
{
"id": 1,
"organization_id": 1,
"namespace_id": 5,
"name": "Block settings changes on critical findings",
"description": null,
"version": 1,
"trigger_type": "project.before_settings_update",
"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 /groups/:id/security/policy_store
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer 또는 string | 예 | 그룹의 ID 또는 URL 인코딩된 경로입니다. |
name |
string | 예 | 정책의 이름입니다. 최대 255자입니다. 조직 내에서 고유해야 합니다. |
rules |
array | 예 | 정책의 규칙입니다. 항목 속성은 규칙 및 액션 속성을 참조합니다. 항목이 하나 이상 필요하며 최대 5개입니다. 각 항목은 직렬화했을 때 최대 4096바이트여야 합니다. 항목이 65536바이트보다 큰 Rego 모듈로 컴파일되면 거부됩니다. 이 모듈은 policy_rego로 반환됩니다. |
trigger_type |
string | 예 | 정책이 반응하는 트리거입니다. 모든 트리거 목록 조회에서 반환되는 ID 중 하나입니다. 이 트리거만 그룹 계층 구조를 담고 있으므로 project.before_settings_update, project.after_create, project.after_transfer 중 하나여야 합니다. |
actions |
array | 아니요 | 정책이 수행하는 액션입니다. 항목 속성은 규칙 및 액션 속성을 참조합니다. 최대 5개 항목입니다. 각 항목은 직렬화했을 때 최대 4096바이트여야 합니다. |
description |
string | 아니요 | 정책에 대한 설명입니다. 최대 4096자입니다. |
lifecycle_state |
string | 아니요 | active 또는 disabled입니다. 기본값은 active입니다. |
mode |
string | 아니요 | audit, warn, enforce 중 하나입니다. 기본값은 warn입니다. |
policy_scope |
object | 아니요 | GitLab이 scope_rego로 컴파일하는 정책의 구조화된 범위입니다. 속성은 정책 범위 속성을 참조합니다. 비어 있지 않은 scope_rego와 함께 사용할 수 없습니다. 4096자를 초과하는 Rego로 컴파일되면 거부됩니다. |
scope_rego |
string | 아니요 | Rego 프로그램으로 직접 작성한 정책의 범위입니다. GitLab은 작성한 그대로 저장합니다. 최대 4096자입니다. 비어 있지 않은 값은 policy_scope와 함께 사용할 수 없습니다. 빈 값은 생략한 것과 효과가 같습니다. Rego로 구문 분석되지 않는 값은 400 Bad Request를 반환합니다. |
성공하면 201 Created와
정책 속성을 반환합니다.
다음 조건에서는 400 Bad Request를 반환합니다.
- 속성이 유효하지 않습니다.
- 두 가지 범위 형식이 모두 제공되었습니다.
- 조직에서 이미 사용 중인 이름입니다.
- 컴파일된
scope_rego가 4096자를 초과합니다. rules가 65536바이트를 초과하는 Rego로 컴파일됩니다.rules또는actions에 항목이 5개를 초과합니다.rules또는actions의 항목이 직렬화했을 때 4096바이트를 초과합니다.trigger_type이 그룹 정책에서 사용할 수 없는 값입니다.
요청 예시:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--data '{
"name": "Block settings changes on critical findings",
"trigger_type": "project.before_settings_update",
"rules": [{ "type": "custom", "value": "package governance" }],
"actions": [{ "type": "block" }],
"policy_scope": { "compliance_frameworks": [{ "id": 5 }] }
}' \
--url "https://gitlab.example.com/api/v4/groups/5/security/policy_store"
응답 예시:
{
"id": 1,
"organization_id": 1,
"namespace_id": 5,
"name": "Block settings changes on critical findings",
"description": null,
"version": 1,
"trigger_type": "project.before_settings_update",
"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": "warn",
"lifecycle_state": "active",
"created_at": "2026-08-07T13:56:32.985Z",
"updated_at": "2026-08-07T13:56:32.985Z"
}
그룹 정책 업데이트#
그룹의 정책을 업데이트합니다.
경로 매개변수 외의 모든 속성은 선택 사항이지만, 요청은 하나 이상을 지정해야 합니다.
보내지 않은 속성은 그대로 유지되며, 값이 하나라도 바뀌는 업데이트는 version을 1 올립니다.
저장된 값을 그대로 다시 보내는 요청은 아무것도 변경하지 않으며 version도 그대로 둡니다.
PATCH /groups/:id/security/policy_store/:policy_id
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer 또는 string | 예 | 그룹의 ID 또는 URL 인코딩된 경로입니다. |
policy_id |
integer | 예 | 정책의 ID입니다. |
actions |
array | 아니요 | 정책이 수행하는 액션입니다. 항목 속성은 규칙 및 액션 속성을 참조합니다. 저장된 액션을 대체하며, 최대 5개 항목입니다. 각 항목은 직렬화했을 때 최대 4096바이트여야 합니다. |
description |
string | 아니요 | 정책에 대한 설명입니다. 최대 4096자입니다. |
lifecycle_state |
string | 아니요 | active 또는 disabled입니다. |
mode |
string | 아니요 | audit, warn, enforce 중 하나입니다. |
name |
string | 아니요 | 정책의 이름입니다. 최대 255자입니다. 조직 내에서 고유해야 합니다. |
policy_scope |
object | 아니요 | GitLab이 scope_rego로 컴파일하는 정책의 구조화된 범위입니다. 속성은 정책 범위 속성을 참조합니다. 비어 있지 않은 scope_rego와 함께 사용할 수 없습니다. 4096자를 초과하는 Rego로 컴파일되면 거부됩니다. |
rules |
array | 아니요 | 정책의 규칙입니다. 항목 속성은 규칙 및 액션 속성을 참조합니다. 저장된 규칙을 대체하며, 최대 5개 항목입니다. 각 항목은 직렬화했을 때 최대 4096바이트여야 합니다. 항목이 65536바이트보다 큰 Rego 모듈로 컴파일되면 거부됩니다. 이 모듈은 policy_rego로 반환됩니다. |
scope_rego |
string | 아니요 | Rego 프로그램으로 직접 작성한 정책의 범위입니다. GitLab은 작성한 그대로 저장합니다. 최대 4096자입니다. 직접 작성한 프로그램을 폐기하고 policy_scope에서 다시 컴파일하려면 빈 값을 보냅니다. Rego로 구문 분석되지 않는 값은 400 Bad Request를 반환합니다. |
trigger_type |
string | 아니요 | 정책이 반응하는 트리거입니다. 모든 트리거 목록 조회에서 반환되는 ID 중 하나입니다. 이 트리거만 그룹 계층 구조를 담고 있으므로 project.before_settings_update, project.after_create, project.after_transfer 중 하나여야 합니다. |
정책의 이름을 바꾸면 생성된 프로그램에 정책 이름이 들어 있으므로,
GitLab은 생성된 scope_rego를 다시 컴파일해야 합니다.
직접 작성한 scope_rego는 그대로 유지됩니다.
성공하면 200 OK와
정책 속성을 반환합니다.
다음 조건에서는 400 Bad Request를 반환합니다.
- 변경할 속성이 지정되지 않았습니다.
- 속성이 유효하지 않습니다.
- 두 가지 범위 형식이 모두 제공되었습니다.
- 새 이름이 조직에서 이미 사용 중입니다.
- 다시 컴파일된
scope_rego가 4096자를 초과합니다. - 대체할
rules가 65536바이트를 초과하는 Rego로 컴파일됩니다. - 대체할
rules또는actions에 항목이 5개를 초과합니다. - 대체할
rules또는actions의 항목이 직렬화했을 때 4096바이트를 초과합니다. - 새
trigger_type이 그룹 정책에서 사용할 수 없는 값입니다.
요청 예시:
curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
--data-urlencode "name=Renamed policy" \
--url "https://gitlab.example.com/api/v4/groups/5/security/policy_store/1"
응답 예시:
{
"id": 1,
"organization_id": 1,
"namespace_id": 5,
"name": "Renamed policy",
"description": null,
"version": 2,
"trigger_type": "project.before_settings_update",
"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 /groups/:id/security/policy_store/:policy_id
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer 또는 string | 예 | 그룹의 ID 또는 URL 인코딩된 경로입니다. |
policy_id |
integer | 예 | 정책의 ID입니다. |
성공하면 204 No Content를 반환합니다.
요청 예시:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/5/security/policy_store/1"