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

사전 요구 사항#

• 컴플라이언스 프레임워크를 생성·편집·삭제하려면 사용자가 다음 중 하나를 충족해야 합니다.
  • 최상위 그룹에 대한 Owner 권한을 보유합니다.
  • 사용자 지정 역할을 할당받고, 그 역할에 admin_compliance_framework 사용자 지정 권한이 포함되어야 합니다.

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

히스토리

• GitLab 19.0에서 도입되었습니다. 이때
• GitLab 19.1에서 일반 공급으로

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

사용 가능한 템플릿 조회#

사용 가능한 모든 컴플라이언스 프레임워크 템플릿을 조회하려면 다음을 실행합니다.

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
            controls {
              nodes {
                id
                name
                controlId
                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 참조