CodeQL 작업 영역에 대해

CodeQL 작업 영역에 대해

CodeQL 작업 영역은 주로 상호 의존적인 라이브러리와 쿼리 팩 모음을 개발하기 위해 활용됩니다. CodeQL 작업 영역을 사용하면, 쿼리 확인 명령을 실행할 때 작업 영역 내의 모든 CodeQL 팩을 서로의 소스 종속성 으로 활용할 수 있습니다. 이렇게 하면 관련된 여러 CodeQL 팩을 더 쉽게 개발하고 유지 관리하며 게시할 수 있습니다. CodeQL에 대한 자세한 정보는 CodeQL 팩을 사용하여 분석 사용자 지정을(를) 참조하세요.

작업 영역은 일반적으로 단일 Git 리포지토리에 저장되므로 관련 팩을 함께 개발하고 게시할 수 있습니다.

소스 종속성

CodeQL 작업 영역에서는, 작업 영역에 포함된 모든 팩이 서로의 소스 종속성으로 처리됩니다. 다시 말해, 로컬 파일 시스템에서 직접 확인되며 CodeQL 패키지 캐시를 거치지 않습니다.

원본에서 작업 공간 팩이 결정되므로:

• 한 팩의 로컬 변경 내용은 작업 영역의 다른 팩에 즉시 표시됩니다.
• 작업 영역의 종속성이 패키지 캐시에 있는 버전을 덮어씁니다.
• 버전이 작업 영역 콘텐츠에 qlpack.yml 의해 결정되므로 파일의 버전 제약 조건은 작업 영역 종속성에 대해 무시됩니다.

이 동작은 여러 관련 팩을 동시에 개발할 때 특히 유용합니다. 다음은 그 예입니다.

• 종속성은 아직 게시되지 않았으며 로컬로만 존재합니다.
• 여러 팩에서 협력하여 변경 작업을 수행하고 있으며 테스트 중에 각 변경이 서로 조화를 이루어야 합니다.

작업 영역 외부에서 종속성은 패키지 캐시에서 확인되며 에 정의된 qlpack.yml버전 제약 조건과 일치해야 합니다. 작업 영역 내에서 해결은 대신 로컬 원본 콘텐츠의 우선 순위를 지정합니다.

CodeQL 작업 영역 및 쿼리 확인

작업 영역 종속성 모델은 팩을 설치하고 게시하는 방법에 영향을 줍니다.

• 설치하는 동안 작업 영역에서 찾은 종속성은 패키지 캐시에 다운로드되지 않고 파일에 기록 codeql-pack.lock.yml 되지 않습니다.
• 게시하는 동안 작업 영역에서 제공하는 종속성은 패키지 캐시의 버전이 아닌 로컬 원본 콘텐츠를 사용하여 번들로 제공됩니다.

예를 들어 작업 영역 내의 팩 디렉터리에서 실행 codeql pack install 하면 패키지 캐시에 다운로드하거나 파일에 기록하는 대신 작업 영역에 있는 codeql-pack.lock.yml 모든 종속성이 사용됩니다. CodeQL 팩 만들기 및 작업을(를) 참조하세요.

예시

CodeQL 작업 영역은 codeql-workspace.yml이라는 이름의 YAML 파일로 정의됩니다. 다음 codeql-workspace.yml 파일을 살펴보세요.

provide:
  - "**/qlpack.yml"

다음 CodeQL 라이브러리 팩 qlpack.yml 파일은 작업 영역에 있습니다.

name: my-company/my-library
library: true
version: 1.0.0

다음 CodeQL 쿼리 팩 qlpack.yml 파일은 작업 영역에 있습니다.

name: my-company/my-queries
version: 1.0.0
dependencies:
  my-company/my-library: "*"
  codeql/cpp-all: ~0.2.0

CodeQL 쿼리 팩의 dependencies 블록인 my-company/my-queries는 라이브러리 팩의 버전으로 "*"를 지정합니다. 라이브러리 팩은 이미 codeql-workspace.yml에 원본 종속성으로 정의되어 있으므로, 라이브러리 팩의 콘텐츠는 항상 작업 영역 내에서 확인할 수 있습니다. 이 경우 정의된 모든 버전 제약 조건이 무시됩니다. 원본 종속성을 사용하면 "*" 버전이 작업 영역에서 상속됨을 명시적으로 표시합니다.

쿼리 팩 디렉터리에서 codeql pack install 을 실행하면 적절한 버전의 codeql/cpp-all 가 로컬 패키지 캐시에 다운로드됩니다. 또한 codeql-pack.lock.yml의 확인된 버전을 포함하는 codeql/cpp-all 파일이 생성됩니다. 잠금 파일은 원본 종속성을 기준으로 생성되므로 my-company/my-library 의 항목은 포함되지 않습니다. codeql-pack.lock.yml 파일은 다음과 같은 모양으로 보이게 됩니다.

dependencies:
  codeql/cpp-all:
    version: 0.2.2

쿼리 팩 디렉터리에서 codeql pack publish 을 실행하면 패키지 캐시의 codeql/cpp-all 종속성과 작업 영역의 my-company/my-library이 my-company/my-queries 와 함께 번들로 제공되어 GitHub 컨테이너 레지스트리에 게시됩니다.

          `codeql-workspace.yml` 파일 예시

CodeQL 작업 영역은 codeql-workspace.yml이라는 이름의 YAML 파일로 정의됩니다. 이 파일에는 provide 블록이 포함되어 있으며 선택적으로 ignore 및 registries 블록이 포함되어 있습니다.

•         `provide` 이 블록에는 작업 영역에서 사용할 수 있는 CodeQL 팩을 정의하는 GLOB 패턴 목록이 포함되어 있습니다.
  

•         `ignore` 이 블록에는 작업 영역에서 사용할 수 없는 CodeQL 팩을 정의하는 GLOB 패턴 목록이 포함되어 있습니다.
  

•         `registries` 블록에는 GHES URL과 패키지 패턴 목록이 포함되어 있으며, 이를 통해 CodeQL 팩을 게시하는 데 사용되는 컨테이너 레지스트리를 제어합니다. 
          [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#working-with-codeql-packs-on-ghes)을(를) 참조하세요.
  
          `provide` 또는 `ignore` 섹션의 각 항목은 `qlpack.yml` 파일의 위치에 매핑되어야 합니다. 모든 GLOB 패턴은 작업 영역 파일이 위치한 디렉터리를 기준으로 정의됩니다. 이 파일에 허용되는 패턴 목록은 [@actions/glob](http://github.com/actions/toolkit/tree/main/packages/glob#patterns) 항목을 참조하세요.
  

예를 들어 다음 codeql-workspace.yml 파일은 codeql-packs 디렉터리의 팩을 제외하고 experimental 디렉터리에서 재귀적으로 찾은 모든 CodeQL 팩을 포함하는 작업 영역을 정의합니다. registries 블록은 GitHub의 기본 컨테이너 레지스트리인 codeql/\*에서 http://ghcr.io/v2/ 팩을 다운로드해야 한다고 지정합니다. 다른 모든 팩은 다운로드한 후 GHE_HOSTNAME의 레지스트리에 게시해야 합니다.

provide:
  - "*/codeql-packs/**/qlpack.yml"
ignore:
  - "*/codeql-packs/**/experimental/**/qlpack.yml"

registries:
 - packages: 'codeql/*'
   url: http://ghcr.io/v2/

 - packages: '*'
   url: http://containers.GHE_HOSTNAME/v2/

작업 영역 디렉터리에서 실행 codeql pack ls 하여 작업 영역에 포함된 팩을 나열할 수 있습니다.

          `${workspace}` 파일에서 버전 범위로 `qlpack.yml` 사용

작업 영역의 CodeQL 팩은 특수 ${workspace}, ~${workspace} 및 ^${workspace} 버전 범위 자리 표시자를 사용할 수 있습니다. 이 자리 표시자는 현재 작업 영역에 있는 특정 팩의 버전에 따라 이 팩의 내용이 달라질 수 있음을 의미합니다. 이 자리 표시자는 일반적으로 라이브러리 팩 내의 종속성에 사용되며, 게시 시점의 작업 영역 상태를 qlpack.yml 파일의 종속성에 반영하기 위해 사용됩니다.

예시

동일한 작업 영역에 있는 다음 두 라이브러리 팩을 고려해보세요.

name: my-company/my-library
library: true
version: 1.2.3
dependencies:
  my-company/my-library2: ${workspace}

name: my-company/my-library2
library: true
version: 4.5.6

          `my-company/my-library`가 GitHub 컨테이너 레지스트리에 게시되면, 게시된 `my-company/my-library2` 파일의 `qlpack.yml` 종속성 버전이 `4.5.6`으로 기록됩니다.

마찬가지로 소스 팩의 종속성이 my-company/my-library2: ^${workspace} 인 상태에서 팩이 게시되면, 게시된 my-company/my-library2 파일의 qlpack.yml 종속성 버전은 ^4.5.6로 작성됩니다. 이는 >= 4.5.6와 < 5.0.0 버전이 모두 해당 라이브러리 팩과 호환됨을 의미합니다.

마찬가지로 소스 팩의 종속성이 my-company/my-library2: ~${workspace} 일 때 해당 팩이 게시되면, 게시된 my-company/my-library2 파일의 qlpack.yml 종속성 버전은 ~4.5.6로 작성됩니다. 이는 >= 4.5.6와 < 4.6.0 버전이 모두 이 라이브러리 팩과 호환됨을 의미합니다.