doc/api/graphql/compliance_frameworks.md
{{< details >}}
{{< /details >}}
Manage compliance frameworks for top-level groups by using a GraphQL API.
admin_compliance_framework
custom permission.Create a new compliance framework for a top-level group.
To create a compliance framework, use the createComplianceFramework mutation:
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:
errors object is empty.200 OK.{{< details >}}
{{< /details >}}
You can create frameworks with specific requirements and controls:
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 by using the framework ID returned by the creation mutation.
List all compliance frameworks for a top-level group.
You can view a list of compliance frameworks for a top-level group by using the group query:
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.
query {
project(fullPath: "my-project"){
id
name
complianceFrameworks{
nodes{
id
name
}
}
}
}
Replace "my-project" with your project's full path.
Update an existing compliance framework 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 for the group.
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:
errors object is empty.200 OK.Delete a compliance framework from a top-level group.
To delete a compliance framework, use the destroyComplianceFramework mutation. You can retrieve the framework ID
by listing all compliance frameworks for the group.
mutation {
destroyComplianceFramework(input: {
id: "gid://gitlab/ComplianceManagement::Framework/1"
}) {
errors
}
}
The framework is deleted if:
errors object is empty.200 OK.Apply one or more compliance frameworks to projects.
Prerequisites:
To apply compliance frameworks to a project, use the projectUpdateComplianceFrameworks mutation:
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:
errors object is empty.200 OK.To remove all compliance frameworks from a project, pass an empty array:
mutation {
projectUpdateComplianceFrameworks(input: {
projectId: "gid://gitlab/Project/1",
complianceFrameworkIds: []
}) {
errors
project {
id
complianceFrameworks {
nodes {
id
name
}
}
}
}
}
You can manage requirements and controls for compliance frameworks by using GraphQL.
{{< details >}}
{{< /details >}}
To view requirements and controls for a compliance framework:
query {
group(fullPath: "my-group") {
complianceFrameworks {
nodes {
id
name
requirements {
nodes {
id
name
description
controls {
nodes {
id
name
controlId
controlType
}
}
}
}
}
}
}
}
{{< details >}}
{{< /details >}}
To add a requirement with GitLab compliance controls to an existing framework:
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
}
}
}
}
}
{{< details >}}
{{< /details >}}
To add a requirement with external controls:
mutation {
createComplianceRequirement(
input: {
complianceFrameworkId: "gid://gitlab/ComplianceManagement::Framework/1",
controls: [{
controlType: "external",
name: "external_control",
externalControlName: "ServiceNowApproval",
externalUrl: "https://mycompany.service-now.com/api/approval",
secretToken: "my-secret-key"
}],
params: {
name: "External Approval Requirement",
description: "Require external system approval for deployments"
}
}
) {
errors
requirement {
id
name
description
complianceRequirementsControls {
nodes {
id
name
controlType
externalUrl
}
}
}
}
}
{{< details >}}
{{< /details >}}
To update an existing requirement:
mutation {
updateComplianceRequirement(input: {
id: "gid://gitlab/ComplianceManagement::ComplianceFramework::ComplianceRequirement/1",
params: {
name: "Updated Security Requirement",
description: "Updated security scanning requirement with additional controls"
},
controls: [{
expression: "{\"field\":\"scanner_sast_running\",\"operator\":\"=\",\"value\":true}",
name: "scanner_sast_running"
},
{
expression: "{\"field\":\"scanner_dep_scanning_running\",\"operator\":\"=\",\"value\":true}",
name: "scanner_dep_scanning_running"
},
{
expression: "{\"field\":\"scanner_secret_detection_running\",\"operator\":\"=\",\"value\":true}",
name: "scanner_secret_detection_running"
}]
})
{
errors
requirement {
id
name
description
complianceRequirementsControls {
nodes {
id
name
}
}
}
}
}
{{< details >}}
{{< /details >}}
To delete a requirement from a framework:
mutation {
destroyComplianceRequirement(input: {
id: "gid://gitlab/ComplianceManagement::ComplianceFramework::ComplianceRequirement/1"
}) {
errors
}
}
When working with compliance frameworks via GraphQL, you may encounter the following common errors:
#1f75cb).admin_compliance_framework permission can manage frameworks.Always check the errors field in the response to handle any issues that occur during mutations.