From 7309138eac30af3b114f96e9fd4d9b0fbd177a90 Mon Sep 17 00:00:00 2001 From: Nate Rosandich Date: Wed, 17 Sep 2025 11:28:05 +1200 Subject: [PATCH 1/4] Add comprehensive GraphQL examples for compliance frameworks - Create new doc/api/graphql/compliance_frameworks.md - Include examples for creating, updating, and deleting frameworks - Add examples for managing requirements and controls - Show how to apply frameworks to projects via GraphQL - Follow existing GraphQL documentation patterns --- doc/api/graphql/compliance_frameworks.md | 439 +++++++++++++++++++++++ 1 file changed, 439 insertions(+) create mode 100644 doc/api/graphql/compliance_frameworks.md diff --git a/doc/api/graphql/compliance_frameworks.md b/doc/api/graphql/compliance_frameworks.md new file mode 100644 index 00000000000000..2214869f7a94a9 --- /dev/null +++ b/doc/api/graphql/compliance_frameworks.md @@ -0,0 +1,439 @@ +--- +stage: Software Supply Chain Security +group: Compliance +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +title: Compliance frameworks GraphQL API +--- + +{{< details >}} + +- Tier: Premium, Ultimate +- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated + +{{< /details >}} + +{{< history >}} + +- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13295) in GitLab 17.3. +- Requirements and controls [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/186525) in GitLab 17.11. + +{{< /history >}} + +Manage compliance frameworks for top-level groups by using a GraphQL API. + +## Prerequisites + +- To create, edit, and delete compliance frameworks, users must have either: + - The Owner role for the top-level group. + - Be assigned a [custom role](../../user/custom_roles/_index.md) with the `admin_compliance_framework` + [custom permission](../../user/custom_roles/abilities.md#compliance-management). + +## Create a compliance framework + +Create a new compliance framework for a top-level group. + +Prerequisites: + +- Owner role for a top-level group. + +To create a compliance framework, use the `createComplianceFramework` mutation: + +```graphql +mutation { + createComplianceFramework(input: { + namespacePath: "my-group", + params: { + name: "SOX Compliance", + description: "Sarbanes-Oxley compliance framework for financial reporting", + color: "#1f75cb", + default: false + } + }) { + errors + framework { + id + name + description + color + default + namespace { + name + } + } + } +} +``` + +The framework is created if: + +- The returned `errors` object is empty. +- The API responds with `200 OK`. + +### Create a framework with requirements (Ultimate only) + +In GitLab Ultimate, you can create frameworks with specific requirements and controls: + +```graphql +mutation { + createComplianceFramework(input: { + namespacePath: "my-group", + params: { + name: "Security Framework", + description: "Security compliance framework with SAST and dependency scanning", + color: "#e24329", + default: false + } + }) { + errors + framework { + id + name + description + color + default + namespace { + name + } + } + } +} +``` + +After creating the framework, you can add requirements using the framework ID returned from the creation mutation. + +## List compliance frameworks + +List all compliance frameworks for a top-level group. + +Prerequisites: + +- Owner role for a top-level group. + +You can view a list of compliance frameworks for a top-level group using the `group` query: + +```graphql +query { + group(fullPath: "my-group") { + id + complianceFrameworks { + nodes { + id + name + description + color + default + pipelineConfigurationFullPath + } + } + } +} +``` + +If the resulting list is empty, then no compliance frameworks exist for that group. + +## Update a compliance framework + +Update an existing compliance framework for a top-level group. + +Prerequisites: + +- Owner role for a top-level group. + +To update a compliance framework, use the `updateComplianceFramework` mutation. You can retrieve the framework ID +by [listing all compliance frameworks](#list-compliance-frameworks) for the group. + +```graphql +mutation { + updateComplianceFramework(input: { + id: "gid://gitlab/ComplianceManagement::Framework/1", + params: { + name: "Updated SOX Compliance", + description: "Updated Sarbanes-Oxley compliance framework", + color: "#6b4fbb", + default: true + } + }) { + errors + framework { + id + name + description + color + default + namespace { + name + } + } + } +} +``` + +The framework is updated if: + +- The returned `errors` object is empty. +- The API responds with `200 OK`. + +## Delete a compliance framework + +Delete a compliance framework from a top-level group. + +Prerequisites: + +- Owner role for a top-level group. + +To delete a compliance framework, use the `destroyComplianceFramework` mutation. You can retrieve the framework ID +by [listing all compliance frameworks](#list-compliance-frameworks) for the group. + +```graphql +mutation { + destroyComplianceFramework(input: { + id: "gid://gitlab/ComplianceManagement::Framework/1" + }) { + errors + } +} +``` + +The framework is deleted if: + +- The returned `errors` object is empty. +- The API responds with `200 OK`. + +## Apply compliance frameworks to projects + +Apply one or more compliance frameworks to projects. + +Prerequisites: + +- Maintainer role or higher for the project. +- The project must belong to a group that has compliance frameworks. + +To apply compliance frameworks to a project, use the `projectUpdateComplianceFrameworks` mutation: + +```graphql +mutation { + projectUpdateComplianceFrameworks(input: { + projectId: "gid://gitlab/Project/1", + complianceFrameworkIds: [ + "gid://gitlab/ComplianceManagement::Framework/1", + "gid://gitlab/ComplianceManagement::Framework/2" + ] + }) { + errors + project { + id + complianceFrameworks { + nodes { + id + name + color + } + } + } + } +} +``` + +The frameworks are applied if: + +- The returned `errors` object is empty. +- The API responds with `200 OK`. + +### Remove compliance frameworks from projects + +To remove all compliance frameworks from a project, pass an empty array: + +```graphql +mutation { + projectUpdateComplianceFrameworks(input: { + projectId: "gid://gitlab/Project/1", + complianceFrameworkIds: [] + }) { + errors + project { + id + complianceFrameworks { + nodes { + id + name + } + } + } + } +} +``` + +## Working with requirements and controls (Ultimate only) + +{{< details >}} + +- Tier: Ultimate +- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated + +{{< /details >}} + +In GitLab Ultimate, you can manage requirements and controls for compliance frameworks using GraphQL. + +### Query framework requirements + +To view requirements and controls for a compliance framework: + +```graphql +query { + group(fullPath: "my-group") { + complianceFrameworks { + nodes { + id + name + requirements { + nodes { + id + name + description + controls { + nodes { + id + name + controlId + controlType + } + } + } + } + } + } + } +} +``` + +### Add requirements to a framework + +To add a requirement with GitLab compliance controls to an existing framework: + +```graphql +mutation { + complianceFrameworkRequirementCreate(input: { + frameworkId: "gid://gitlab/ComplianceManagement::Framework/1", + name: "Security Scanning Requirement", + description: "Ensure security scanning is enabled for all projects", + controlIds: [ + "scanner_sast_running", + "scanner_dep_scanning_running", + "scanner_secret_detection_running" + ] + }) { + errors + requirement { + id + name + description + controls { + nodes { + id + name + controlId + } + } + } + } +} +``` + +### Add external controls + +To add a requirement with external controls: + +```graphql +mutation { + complianceFrameworkRequirementCreate(input: { + frameworkId: "gid://gitlab/ComplianceManagement::Framework/1", + name: "External Approval Requirement", + description: "Require external system approval for deployments", + externalControls: [{ + name: "ServiceNow Approval", + externalUrl: "https://mycompany.service-now.com/api/approval", + hmacSharedSecret: "my-secret-key" + }] + }) { + errors + requirement { + id + name + description + controls { + nodes { + id + name + controlType + externalUrl + } + } + } + } +} +``` + +### Update requirements + +To update an existing requirement: + +```graphql +mutation { + complianceFrameworkRequirementUpdate(input: { + id: "gid://gitlab/ComplianceManagement::Requirement/1", + name: "Updated Security Requirement", + description: "Updated security scanning requirement with additional controls", + controlIds: [ + "scanner_sast_running", + "scanner_dep_scanning_running", + "scanner_secret_detection_running", + "scanner_container_scanning_running" + ] + }) { + errors + requirement { + id + name + description + controls { + nodes { + id + name + controlId + } + } + } + } +} +``` + +### Delete requirements + +To delete a requirement from a framework: + +```graphql +mutation { + complianceFrameworkRequirementDestroy(input: { + id: "gid://gitlab/ComplianceManagement::Requirement/1" + }) { + errors + } +} +``` + +## Error handling + +When working with compliance frameworks via GraphQL, you may encounter the following common errors: + +- **Framework name already exists**: Each framework name must be unique within a group. +- **Invalid color format**: Colors must be in hexadecimal format (e.g., `#1f75cb`). +- **Insufficient permissions**: Only group owners or users with the `admin_compliance_framework` permission can manage frameworks. +- **Invalid control ID**: Control IDs must match the supported [GitLab compliance controls](../../user/compliance/compliance_frameworks/_index.md#gitlab-compliance-controls). + +Always check the `errors` field in the response to handle any issues that occur during mutations. + +## Related topics + +- [Compliance frameworks](../../user/compliance/compliance_frameworks/_index.md) +- [Compliance center](../../user/compliance/compliance_center/_index.md) +- [GraphQL API reference](reference/_index.md) -- GitLab From ba1aad660f8794175bc42d5525fa9ceab5483423 Mon Sep 17 00:00:00 2001 From: Nate Rosandich Date: Wed, 17 Sep 2025 15:21:24 +1200 Subject: [PATCH 2/4] Add JSON schema --- doc/api/graphql/compliance_frameworks.md | 7 -- .../compliance_frameworks/_index.md | 83 +++++++++++++++++++ 2 files changed, 83 insertions(+), 7 deletions(-) diff --git a/doc/api/graphql/compliance_frameworks.md b/doc/api/graphql/compliance_frameworks.md index 2214869f7a94a9..79893484882f0c 100644 --- a/doc/api/graphql/compliance_frameworks.md +++ b/doc/api/graphql/compliance_frameworks.md @@ -12,13 +12,6 @@ title: Compliance frameworks GraphQL API {{< /details >}} -{{< history >}} - -- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13295) in GitLab 17.3. -- Requirements and controls [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/186525) in GitLab 17.11. - -{{< /history >}} - Manage compliance frameworks for top-level groups by using a GraphQL API. ## Prerequisites diff --git a/doc/user/compliance/compliance_frameworks/_index.md b/doc/user/compliance/compliance_frameworks/_index.md index 99a8c81c0fb9f5..b6c5b91552a6c8 100644 --- a/doc/user/compliance/compliance_frameworks/_index.md +++ b/doc/user/compliance/compliance_frameworks/_index.md @@ -167,6 +167,89 @@ To import a compliance framework by using a JSON template: If the import is successful, the new compliance framework appears in the list. Any errors are displayed for correction. +### JSON template structure and schema + +Compliance framework JSON templates follow a specific schema structure that defines the framework metadata, requirements, and associated controls. Understanding this structure helps you create custom templates or modify existing ones to meet your organization's specific compliance needs. + +#### Framework properties + +Each JSON template contains the following top-level properties: + +| Property | Type | Required | Description | +|----------|------|----------|-------------| +| `name` | String | Yes | The display name of the compliance framework | +| `description` | String | Yes | A detailed description of the framework's purpose | +| `color` | String | Yes | Hexadecimal color code for the framework (e.g., `#1f75cb`) | +| `requirements` | Array | No | Array of requirement objects that define the compliance controls | + +#### Requirements structure + +Each requirement in the `requirements` array contains: + +| Property | Type | Required | Description | +|----------|------|----------|-------------| +| `name` | String | Yes | The name of the compliance requirement | +| `description` | String | Yes | Detailed description of what the requirement enforces | +| `controls` | Array | Yes | Array of control objects that implement the requirement | + +#### Control structure + +Each control in the `controls` array defines a specific check: + +| Property | Type | Required | Description | +|----------|------|----------|-------------| +| `name` | String | Yes | The GitLab control ID (e.g., `scanner_sast_running`) | +| `control_type` | String | Yes | Always `"internal"` for GitLab controls | +| `expression` | Object | Yes | Defines the evaluation logic for the control | + +#### Expression object + +The `expression` object defines how the control is evaluated: + +| Property | Type | Required | Description | +|----------|------|----------|-------------| +| `field` | String | Yes | The field name to evaluate (matches the control name) | +| `operator` | String | Yes | Comparison operator (`=`, `>=`, `<=`, `>`, `<`) | +| `value` | Mixed | Yes | Expected value (boolean, number, or string) | + +#### Example JSON template structure + +Here's a simplified example showing the complete structure: + +```json +{ + "name": "Example Compliance Framework", + "description": "Example framework demonstrating JSON structure", + "color": "#1f75cb", + "requirements": [ + { + "name": "Security Scanning Requirement", + "description": "Ensure security scanning is enabled for all projects", + "controls": [ + { + "name": "scanner_sast_running", + "control_type": "internal", + "expression": { + "field": "scanner_sast_running", + "operator": "=", + "value": true + } + }, + { + "name": "minimum_approvals_required_2", + "control_type": "internal", + "expression": { + "field": "minimum_approvals_required", + "operator": ">=", + "value": 2 + } + } + ] + } + ] +} +``` + ## Requirements {{< details >}} -- GitLab From 3b11f7b9e8da9274e7c49c69a034ea668977755f Mon Sep 17 00:00:00 2001 From: Nate Rosandich Date: Fri, 19 Sep 2025 09:58:11 +1200 Subject: [PATCH 3/4] Apply 18 suggestion(s) to 2 file(s) Co-authored-by: Suzanne Selhorn --- doc/api/graphql/compliance_frameworks.md | 43 +++++++------------ .../compliance_frameworks/_index.md | 28 ++++++------ 2 files changed, 30 insertions(+), 41 deletions(-) diff --git a/doc/api/graphql/compliance_frameworks.md b/doc/api/graphql/compliance_frameworks.md index 79893484882f0c..3e91f540c6d23a 100644 --- a/doc/api/graphql/compliance_frameworks.md +++ b/doc/api/graphql/compliance_frameworks.md @@ -16,8 +16,8 @@ Manage compliance frameworks for top-level groups by using a GraphQL API. ## Prerequisites -- To create, edit, and delete compliance frameworks, users must have either: - - The Owner role for the top-level group. +- To create, edit, and delete compliance frameworks, users either: + - Have the Owner role for the top-level group. - Be assigned a [custom role](../../user/custom_roles/_index.md) with the `admin_compliance_framework` [custom permission](../../user/custom_roles/abilities.md#compliance-management). @@ -25,10 +25,6 @@ Manage compliance frameworks for top-level groups by using a GraphQL API. Create a new compliance framework for a top-level group. -Prerequisites: - -- Owner role for a top-level group. - To create a compliance framework, use the `createComplianceFramework` mutation: ```graphql @@ -62,9 +58,15 @@ The framework is created if: - The returned `errors` object is empty. - The API responds with `200 OK`. -### Create a framework with requirements (Ultimate only) +### Create a framework with requirements + +{{< details >}} + +- Tier: Ultimate -In GitLab Ultimate, you can create frameworks with specific requirements and controls: +{{< /details >}} + +You can create frameworks with specific requirements and controls: ```graphql mutation { @@ -92,17 +94,13 @@ mutation { } ``` -After creating the framework, you can add requirements using the framework ID returned from the creation mutation. +After creating the framework, you can add requirements by using the framework ID returned by the creation mutation. ## List compliance frameworks List all compliance frameworks for a top-level group. -Prerequisites: - -- Owner role for a top-level group. - -You can view a list of compliance frameworks for a top-level group using the `group` query: +You can view a list of compliance frameworks for a top-level group by using the `group` query: ```graphql query { @@ -128,10 +126,6 @@ If the resulting list is empty, then no compliance frameworks exist for that gro Update an existing compliance framework for a top-level group. -Prerequisites: - -- Owner role for a top-level group. - To update a compliance framework, use the `updateComplianceFramework` mutation. You can retrieve the framework ID by [listing all compliance frameworks](#list-compliance-frameworks) for the group. @@ -170,10 +164,6 @@ The framework is updated if: Delete a compliance framework from a top-level group. -Prerequisites: - -- Owner role for a top-level group. - To delete a compliance framework, use the `destroyComplianceFramework` mutation. You can retrieve the framework ID by [listing all compliance frameworks](#list-compliance-frameworks) for the group. @@ -198,7 +188,7 @@ Apply one or more compliance frameworks to projects. Prerequisites: -- Maintainer role or higher for the project. +- Maintainer or Owner role for the project. - The project must belong to a group that has compliance frameworks. To apply compliance frameworks to a project, use the `projectUpdateComplianceFrameworks` mutation: @@ -256,16 +246,15 @@ mutation { } ``` -## Working with requirements and controls (Ultimate only) +## Working with requirements and controls {{< details >}} - Tier: Ultimate -- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated {{< /details >}} -In GitLab Ultimate, you can manage requirements and controls for compliance frameworks using GraphQL. +You can manage requirements and controls for compliance frameworks by using GraphQL. ### Query framework requirements @@ -419,7 +408,7 @@ mutation { When working with compliance frameworks via GraphQL, you may encounter the following common errors: - **Framework name already exists**: Each framework name must be unique within a group. -- **Invalid color format**: Colors must be in hexadecimal format (e.g., `#1f75cb`). +- **Invalid color format**: Colors must be in hexadecimal format (for example, `#1f75cb`). - **Insufficient permissions**: Only group owners or users with the `admin_compliance_framework` permission can manage frameworks. - **Invalid control ID**: Control IDs must match the supported [GitLab compliance controls](../../user/compliance/compliance_frameworks/_index.md#gitlab-compliance-controls). diff --git a/doc/user/compliance/compliance_frameworks/_index.md b/doc/user/compliance/compliance_frameworks/_index.md index b6c5b91552a6c8..1e4792e30acda3 100644 --- a/doc/user/compliance/compliance_frameworks/_index.md +++ b/doc/user/compliance/compliance_frameworks/_index.md @@ -177,10 +177,10 @@ Each JSON template contains the following top-level properties: | Property | Type | Required | Description | |----------|------|----------|-------------| -| `name` | String | Yes | The display name of the compliance framework | -| `description` | String | Yes | A detailed description of the framework's purpose | -| `color` | String | Yes | Hexadecimal color code for the framework (e.g., `#1f75cb`) | -| `requirements` | Array | No | Array of requirement objects that define the compliance controls | +| `name` | String | Yes | The display name of the compliance framework. | +| `description` | String | Yes | A detailed description of the framework's purpose. | +| `color` | String | Yes | Hexadecimal color code for the framework (for example, `#1f75cb`). | +| `requirements` | Array | No | Array of requirement objects that define the compliance controls. | #### Requirements structure @@ -188,9 +188,9 @@ Each requirement in the `requirements` array contains: | Property | Type | Required | Description | |----------|------|----------|-------------| -| `name` | String | Yes | The name of the compliance requirement | -| `description` | String | Yes | Detailed description of what the requirement enforces | -| `controls` | Array | Yes | Array of control objects that implement the requirement | +| `name` | String | Yes | The name of the compliance requirement. | +| `description` | String | Yes | Detailed description of what the requirement enforces. | +| `controls` | Array | Yes | Array of control objects that implement the requirement. | #### Control structure @@ -198,9 +198,9 @@ Each control in the `controls` array defines a specific check: | Property | Type | Required | Description | |----------|------|----------|-------------| -| `name` | String | Yes | The GitLab control ID (e.g., `scanner_sast_running`) | -| `control_type` | String | Yes | Always `"internal"` for GitLab controls | -| `expression` | Object | Yes | Defines the evaluation logic for the control | +| `name` | String | Yes | The GitLab control ID (for example, `scanner_sast_running`). | +| `control_type` | String | Yes | Always `"internal"` for GitLab controls. | +| `expression` | Object | Yes | Defines the evaluation logic for the control. | #### Expression object @@ -208,13 +208,13 @@ The `expression` object defines how the control is evaluated: | Property | Type | Required | Description | |----------|------|----------|-------------| -| `field` | String | Yes | The field name to evaluate (matches the control name) | -| `operator` | String | Yes | Comparison operator (`=`, `>=`, `<=`, `>`, `<`) | -| `value` | Mixed | Yes | Expected value (boolean, number, or string) | +| `field` | String | Yes | The field name to evaluate (matches the control name). | +| `operator` | String | Yes | Comparison operator (`=`, `>=`, `<=`, `>`, `<`). | +| `value` | Mixed | Yes | Expected value (boolean, number, or string). | #### Example JSON template structure -Here's a simplified example showing the complete structure: +Here's a simplified example that shows the complete structure: ```json { -- GitLab From f8af92fb4df243191677d53f938505203f573f9f Mon Sep 17 00:00:00 2001 From: Suzanne Selhorn Date: Thu, 18 Sep 2025 15:28:59 -0700 Subject: [PATCH 4/4] Apply 6 suggestion(s) to 1 file(s) --- doc/api/graphql/compliance_frameworks.md | 32 +++++++++++++++++++++--- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/doc/api/graphql/compliance_frameworks.md b/doc/api/graphql/compliance_frameworks.md index 3e91f540c6d23a..391e14e3c99f62 100644 --- a/doc/api/graphql/compliance_frameworks.md +++ b/doc/api/graphql/compliance_frameworks.md @@ -248,16 +248,16 @@ mutation { ## Working with requirements and controls +You can manage requirements and controls for compliance frameworks by using GraphQL. + +### Query framework requirements + {{< details >}} - Tier: Ultimate {{< /details >}} -You can manage requirements and controls for compliance frameworks by using GraphQL. - -### Query framework requirements - To view requirements and controls for a compliance framework: ```graphql @@ -290,6 +290,12 @@ query { ### Add requirements to a framework +{{< details >}} + +- Tier: Ultimate + +{{< /details >}} + To add a requirement with GitLab compliance controls to an existing framework: ```graphql @@ -323,6 +329,12 @@ mutation { ### Add external controls +{{< details >}} + +- Tier: Ultimate + +{{< /details >}} + To add a requirement with external controls: ```graphql @@ -357,6 +369,12 @@ mutation { ### Update requirements +{{< details >}} + +- Tier: Ultimate + +{{< /details >}} + To update an existing requirement: ```graphql @@ -391,6 +409,12 @@ mutation { ### Delete requirements +{{< details >}} + +- Tier: Ultimate + +{{< /details >}} + To delete a requirement from a framework: ```graphql -- GitLab