CodeQL 작업 영역 정보

CodeQL 작업 영역 정보

여러 CodeQL 팩을 함께 그룹화하려는 경우 CodeQL 작업 영역을 사용합니다. CodeQL 작업 영역의 일반적인 사용 사례는 상호 종속된 CodeQL 라이브러리 및 쿼리 팩 집합을 개발하는 것입니다. CodeQL에 대한 자세한 정보는 “CodeQL 팩을 사용하여 분석 사용자 지정”을(를) 참조하세요.

CodeQL 작업 영역의 주요 이점은 여러 CodeQL 팩을 더 쉽게 개발하고 유지 관리할 수 있다는 것입니다. CodeQL 작업 영역을 사용하는 경우 쿼리를 확인하는 CodeQL 명령을 실행할 때 작업 영역의 모든 CodeQL 팩을 서로에 대한 _원본 종속성_으로 사용할 수 있습니다. 이렇게 하면 관련된 여러 CodeQL 팩을 더 쉽게 개발, 유지 관리 및 게시할 수 있습니다.

대부분의 경우 CodeQL 작업 영역과 CodeQL 팩을 하나의 git 리포지토리에 저장해야 합니다. 이렇게 하면 CodeQL 개발 환경을 더 쉽게 공유할 수 있습니다.

codeql-workspace.yml 파일

CodeQL 작업 영역은 codeql-workspace.yml yaml 파일로 정의됩니다. 이 파일에는 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 블록은 GitHub의 기본 컨테이너 레지스트리인 https://ghcr.io/v2/에서 codeql/\* 팩을 다운로드해야 한다고 지정합니다. 다른 모든 팩은 다운로드하여 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-workspace.yml 파일에 예상한 CodeQL 팩이 포함되어 있는지 확인하려면 작업 영역과 동일한 디렉터리에서 codeql pack ls 명령을 실행합니다. 명령의 결과는 작업 영역의 모든 CodeQL 팩의 목록입니다.

원본 종속성

원본 종속성은 CodeQL 패키지 캐시 외부의 로컬 파일 시스템에서 확인된 CodeQL 팩입니다. 이러한 종속성은 동일한 CodeQL 작업 영역에 있거나 인수를 사용하여 --additional-packs 경로 옵션으로 지정될 수 있습니다. 로컬에서 쿼리를 컴파일하고 실행하는 경우 원본 종속성은 CodeQL 패키지 캐시에 있는 모든 종속성과 qlpack.yml에 정의된 버전 제약 조건을 재정의합니다. 동일한 작업 영역의 CodeQL 팩에 대한 모든 참조는 원본 종속성으로 확인됩니다.

이는 다음과 같은 상황에서 특히 유용합니다.

• 실행 중인 쿼리 팩의 종속성 중 하나가 아직 게시되지 않았습니다. 원본에서 확인하는 것이 해당 팩을 참조하는 유일한 방법입니다.

• 여러 팩을 동시에 변경하고 함께 테스트하려고 합니다. 원본에서 확인하면 팩의 버전을 변경 내용과 함께 사용할 수 있습니다.

CodeQL 작업 영역 및 쿼리 확인

쿼리 또는 팩을 확인하는 CodeQL 명령을 실행할 때 작업 영역의 모든 CodeQL 팩을 서로에 대한 원본 종속성으로 사용할 수 있습니다. 예를 들어 작업 영역의 팩 디렉터리에서 codeql pack install을 실행하면 해당 종속성을 패키지 캐시에 다운로드하고 codeql-pack.lock.yml 파일에 추가하는 대신 작업 영역에서 찾을 수 있는 모든 종속성이 사용됩니다. 자세한 내용은 "CodeQL 팩 만들기 및 작업"을(를) 참조하세요.

마찬가지로 codeql pack publish를 사용하여 CodeQL 쿼리 팩을 GitHub 컨테이너 레지스트리에 게시하면 명령은 로컬 패키지 캐시에 있는 종속성을 사용하는 대신 항상 작업 영역의 종속성을 사용합니다.

이렇게 하면 종속성에서 쿼리 라이브러리에 대한 로컬 변경 내용이 해당 작업 영역에서 게시하는 모든 쿼리 팩에 자동으로 반영됩니다.

예시

다음 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/cpp-all의 확인된 버전을 포함하는 codeql-pack.lock.yml 파일이 생성됩니다. 잠금 파일은 원본 종속성에서 확인되므로 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 컨테이너 레지지스트리에 게시됩니다.

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

작업 영역의 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 컨테이너 레지스트리에 게시되면, 게시된 qlpack.yml 파일의 my-company/my-library2 종속성 버전이 4.5.6으로 기록됩니다.

마찬가지로, 소스 팩의 종속성이 my-company/my-library2: ^${workspace}이고 팩이 게시되면 게시된 qlpack.yml 파일의 my-company/my-library2 종속성 버전은 ^4.5.6으로 작성되어 >= 4.5.6 및 < 5.0.0 버전이 모두 이 라이브러리 팩과 호환됨을 나타냅니다.

소스 팩의 종속성이 my-company/my-library2: ~${workspace}이고 팩이 게시되면 게시된 qlpack.yml 파일의 my-company/my-library2 종속성 버전은 ~4.5.6으로 작성되어 >= 4.5.6 및 < 4.6.0 버전이 모두 이 라이브러리 팩과 호환됨을 나타냅니다.