CodeQL 작업 영역에 대해

CodeQL 작업 영역을 사용하면 서로 의존하는 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 블록에는 GHES URL과 패키지 패턴 목록이 포함되어 있으며, 이를 통해 CodeQL 팩을 게시하는 데 사용되는 컨테이너 레지스트리를 제어합니다. 자세한 내용은 CodeQL 팩 게시 및 사용을(를) 참조하세요.

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

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

${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 버전이 모두 이 라이브러리 팩과 호환됨을 의미합니다.