CodeQL 작업 영역

작업 영역 정보 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 팩 만들기 및 작업을(를) 참조하세요.

Example

CodeQL 작업 영역은 이름이 codeql-workspace.ymlYAML 파일로 정의됩니다. 다음 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.ymlYAML 파일로 정의됩니다. 이 파일에는 provide 블록이 포함되어 있으며 선택적으로 ignore 및 registries 블록이 포함되어 있습니다.

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

• ignore 블록에는 워크스페이스에서 사용할 수 없는 CodeQL 팩을 정의하는 glob 패턴 목록이 포함되어 있습니다.

• 블록에는 registries 게시 CodeQL 팩에 사용되는 컨테이너 레지스트리를 제어하는 GHES URL 및 패키지 패턴 목록이 포함되어 있습니다. CodeQL 팩 게시 및 사용을(를) 참조하세요.

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

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

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 pack ls 하여 작업 영역에 포함된 팩을 나열할 수 있습니다.

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

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

Example

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

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 컨테이너 레지스트리에 게시되면 게시된 qlpack.yml 파일의 my-company/my-library2 종속성 버전은 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 버전이 모두 이 라이브러리 팩과 호환됨을 의미합니다.