GraphQL API를 사용하여 최상위 그룹의 컴플라이언스 프레임워크를 관리합니다.

사전 요건#

• 컴플라이언스 프레임워크를 생성, 편집, 삭제하려면 다음 중 하나여야 합니다:
  • 최상위 그룹에 대한 Owner 역할.
  • admin_compliance_framework 커스텀 권한이 있는 커스텀 역할에 배정.

템플릿에서 컴플라이언스 프레임워크 생성#

히스토리

• GitLab 19.0에서 compliance_framework_templates 플래그와 함께 도입됨. 기본적으로 비활성화되어 있습니다.

사전 정의된 템플릿으로 컴플라이언스 프레임워크를 생성합니다. 템플릿에는 일반적인 컴플라이언스 표준에 맞춰 사전 구성된 요건과 컨트롤이 포함되어 있습니다.

사용 가능한 템플릿 목록 조회#

모든 사용 가능한 컴플라이언스 프레임워크 템플릿을 나열하려면:

query {
  complianceFrameworkTemplates {
    id
    name
    description
    color
    templateVersion
  }
}

특정 템플릿을 ID로 가져오고 전체 JSON 구조를 보려면:

query {
  complianceFrameworkTemplates(
    id: "gid://gitlab/ComplianceManagement::Frameworks::TemplateRegistry::Template/soc2"
  ) {
    id
    name
    description
    color
    templateVersion
    json
  }
}

사용 가능한 템플릿 ID:

템플릿에서 프레임워크 생성#

템플릿에서 컴플라이언스 프레임워크를 생성하려면 createComplianceFrameworkFromTemplate 뮤테이션을 사용합니다. templateId와 namespacePath 인수는 필수입니다. 그 외 인수는 템플릿 기본값을 재정의하는 선택적 인수입니다.

mutation {
  createComplianceFrameworkFromTemplate(
    input: {
      namespacePath: "my-group"
      templateId: "gid://gitlab/ComplianceManagement::Frameworks::TemplateRegistry::Template/soc2"
    }
  ) {
    framework {
      id
      name
      description
      color
    }
    errors
  }
}

템플릿의 기본 이름, 설명, 색상 및 기본 상태를 재정의할 수 있습니다:

mutation {
  createComplianceFrameworkFromTemplate(
    input: {
      namespacePath: "my-group"
      templateId: "gid://gitlab/ComplianceManagement::Frameworks::TemplateRegistry::Template/soc2"
      name: "Custom SOC 2"
      description: "Our organization's SOC 2 compliance framework"
      color: "#FCA121"
      default: true
    }
  ) {
    framework {
      id
      name
      description
      color
    }
    errors
  }
}

프레임워크는 템플릿의 모든 요건과 컨트롤이 미리 채워진 상태로 생성됩니다. 소스 템플릿 ID와 버전은 변경 불가능한 출처 필드로 기록되며 생성 후 변경할 수 없습니다.

다음 조건이 충족되면 프레임워크가 생성됩니다:

• 반환된 errors 객체가 비어 있습니다.
• API가 200 OK로 응답합니다.

컴플라이언스 프레임워크 생성#

최상위 그룹에 대한 새 컴플라이언스 프레임워크를 생성합니다.

컴플라이언스 프레임워크를 생성하려면 createComplianceFramework 뮤테이션을 사용합니다:

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
      }
    }
  }
}

다음 조건이 충족되면 프레임워크가 생성됩니다:

• 반환된 errors 객체가 비어 있습니다.
• API가 200 OK로 응답합니다.

요건이 있는 프레임워크 생성#

특정 요건과 컨트롤로 프레임워크를 생성할 수 있습니다:

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
      }
    }
  }
}

프레임워크를 생성한 후 생성 뮤테이션에서 반환된 프레임워크 ID를 사용하여 요건을 추가할 수 있습니다.

컴플라이언스 프레임워크 목록 조회#

최상위 그룹의 모든 컴플라이언스 프레임워크를 나열합니다.

group 쿼리를 사용하여 최상위 그룹의 컴플라이언스 프레임워크 목록을 볼 수 있습니다:

query {
  group(fullPath: "my-group") {
    id
    complianceFrameworks {
      nodes {
        id
        name
        description
        color
        default
        pipelineConfigurationFullPath
      }
    }
  }
}

결과 목록이 비어 있으면 해당 그룹에 컴플라이언스 프레임워크가 없는 것입니다.

프로젝트에 할당된 컴플라이언스 프레임워크 목록 조회#

query {
 project(fullPath: "my-project"){
  id
  name
  complianceFrameworks{
    nodes{
      id
      name
      }
    }
  }
}

"my-project"를 프로젝트의 전체 경로로 바꾸세요.

컴플라이언스 프레임워크 업데이트#

최상위 그룹의 기존 컴플라이언스 프레임워크를 업데이트합니다.

컴플라이언스 프레임워크를 업데이트하려면 updateComplianceFramework 뮤테이션을 사용합니다. 그룹의 모든 컴플라이언스 프레임워크를 나열하여 프레임워크 ID를 검색할 수 있습니다.

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
      }
    }
  }
}

다음 조건이 충족되면 프레임워크가 업데이트됩니다:

• 반환된 errors 객체가 비어 있습니다.
• API가 200 OK로 응답합니다.

컴플라이언스 프레임워크 삭제#

최상위 그룹에서 컴플라이언스 프레임워크를 삭제합니다.

컴플라이언스 프레임워크를 삭제하려면 destroyComplianceFramework 뮤테이션을 사용합니다. 그룹의 모든 컴플라이언스 프레임워크를 나열하여 프레임워크 ID를 검색할 수 있습니다.

mutation {
  destroyComplianceFramework(input: {
    id: "gid://gitlab/ComplianceManagement::Framework/1"
  }) {
    errors
  }
}

다음 조건이 충족되면 프레임워크가 삭제됩니다:

• 반환된 errors 객체가 비어 있습니다.
• API가 200 OK로 응답합니다.

프로젝트에 컴플라이언스 프레임워크 적용#

프로젝트에 하나 이상의 컴플라이언스 프레임워크를 적용합니다.

사전 요건:

• 프로젝트에 대한 Maintainer 또는 Owner 역할.
• 프로젝트는 컴플라이언스 프레임워크가 있는 그룹에 속해야 합니다.

프로젝트에 컴플라이언스 프레임워크를 적용하려면 projectUpdateComplianceFrameworks 뮤테이션을 사용합니다:

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
        }
      }
    }
  }
}

다음 조건이 충족되면 프레임워크가 적용됩니다:

• 반환된 errors 객체가 비어 있습니다.
• API가 200 OK로 응답합니다.

프로젝트에서 컴플라이언스 프레임워크 제거#

프로젝트에서 모든 컴플라이언스 프레임워크를 제거하려면 빈 배열을 전달합니다:

mutation {
  projectUpdateComplianceFrameworks(input: {
    projectId: "gid://gitlab/Project/1",
    complianceFrameworkIds: []
  }) {
    errors
    project {
      id
      complianceFrameworks {
        nodes {
          id
          name
        }
      }
    }
  }
}

요건 및 컨트롤 작업#

GraphQL을 사용하여 컴플라이언스 프레임워크의 요건과 컨트롤을 관리할 수 있습니다.

프레임워크 요건 쿼리#

컴플라이언스 프레임워크의 요건과 컨트롤을 보려면:

query {
  group(fullPath: "my-group") {
    complianceFrameworks {
      nodes {
        id
        name
        requirements {
          nodes {
            id
            name
            description
            complianceRequirementsControls {
              nodes {
                id
                name
                controlType
              }
            }
          }
        }
      }
    }
  }
}

프레임워크에 요건 추가#

기존 프레임워크에 GitLab 컴플라이언스 컨트롤이 있는 요건을 추가하려면:

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
        }
      }
    }
  }
}

외부 컨트롤 추가#

외부 컨트롤이 있는 요건을 추가하려면:

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
        }
      }
    }
  }
}

요건 업데이트#

기존 요건을 업데이트하려면:

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
        }
      }
    }
  }
}

요건 삭제#

프레임워크에서 요건을 삭제하려면:

mutation {
  destroyComplianceRequirement(input: {
    id: "gid://gitlab/ComplianceManagement::ComplianceFramework::ComplianceRequirement/1"
  }) {
    errors
  }
}

오류 처리#

GraphQL을 통해 컴플라이언스 프레임워크를 다룰 때 다음과 같은 일반적인 오류가 발생할 수 있습니다:

• 프레임워크 이름이 이미 존재함: 각 프레임워크 이름은 그룹 내에서 고유해야 합니다.
• 잘못된 색상 형식: 색상은 16진수 형식이어야 합니다 (예: #1f75cb).
• 권한 부족: 그룹 Owner 또는 admin_compliance_framework 권한이 있는 사용자만 프레임워크를 관리할 수 있습니다.
• 잘못된 컨트롤 ID: 컨트롤 ID는 지원되는 GitLab 컴플라이언스 컨트롤과 일치해야 합니다.

뮤테이션 중에 발생하는 문제를 처리하려면 항상 응답의 errors 필드를 확인하세요.

관련 항목#

• 컴플라이언스 프레임워크
• 컴플라이언스 센터
• GraphQL API 참조