CodeQL 작업 영역에 대해

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

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

소스 종속성

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

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

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

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

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

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

CodeQL 작업 영역 및 쿼리 확인

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

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

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

예시

CodeQL 워크스페이스는 .이라는 이름의 YAML 파일로 정의됩니다. 다음 파일을 고려해보세요.

provide:
  - "**/qlpack.yml"

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

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

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

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

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

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

dependencies:
  codeql/cpp-all:
    version: 0.2.2

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

파일의 예

CodeQL 워크스페이스는 .이라는 이름의 YAML 파일로 정의됩니다. 이 파일에는 블록이 포함되어 있으며 선택적으로 및 블록이 포함되어 있습니다.

이 블록에는 작업 영역에서 사용할 수 있는 CodeQL 팩을 정의하는 GLOB 패턴 목록이 포함되어 있습니다.
이 블록에는 작업 영역에서 사용할 수 없는 CodeQL 팩을 정의하는 GLOB 패턴 목록이 포함되어 있습니다.
블록에는 GHES URL과 패키지 패턴 목록이 포함되어 있으며, 이를 통해 CodeQL 팩을 게시하는 데 사용되는 컨테이너 레지스트리를 제어합니다. AUTOTITLE을(를) 참조하세요.

또는 섹션의 각 항목은 파일의 위치에 매핑되어야 합니다. 모든 GLOB 패턴은 작업 영역 파일이 위치한 디렉터리를 기준으로 정의됩니다. 이 파일에 허용되는 패턴 목록은 항목을 참조하세요.

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

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

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

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

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

파일에서 버전 범위로 사용

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

예시

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

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

가 GitHub 컨테이너 레지스트리에 게시되면, 게시된 파일의 종속성 버전이 으로 기록됩니다.

마찬가지로 소스 팩의 종속성이 인 상태에서 팩이 게시되면, 게시된 파일의 종속성 버전은 로 작성됩니다. 이는 와 버전이 모두 해당 라이브러리 팩과 호환됨을 의미합니다.

마찬가지로 소스 팩의 종속성이 일 때 해당 팩이 게시되면, 게시된 파일의 종속성 버전은 로 작성됩니다. 이는 와 버전이 모두 이 라이브러리 팩과 호환됨을 의미합니다.

CodeQL 작업 영역에 대해

누가 이 기능을 사용할 수 있나요?

이 문서의 내용