Skip to main content

쿼리 도움말 파일 테스트

CodeQL CLI을(를) 사용하여 쿼리 도움말 파일을 Markdown으로 미리 확인하고 유효한지 확인할 수 있습니다.

GitHub CodeQL은(는) 설치 시 사용자별로 라이선스가 부여됩니다. 라이선스 제한에 따라 특정 작업에만 CodeQL을(를) 사용할 수 있습니다. 자세한 내용은 "CodeQL CLI 알아보기"을 참조하세요.

GitHub Advanced Security 라이선스가 있는 경우 CodeQL을(를) 사용하여 분석 자동화, 연속 통합 및 지속적인 업데이트를 할 수 있습니다. 자세한 내용은 "GitHub Advanced Security 정보.

About testing query help files

Test query help files by rendering them as Markdown to ensure they are valid before uploading them to the CodeQL repository or using them in code scanning.

Query help is documentation that accompanies a query to explain how the query works, as well as providing information about the potential problem that the query identifies. It is good practice to write query help for all new queries. For more information, see Contributing to CodeQL in the CodeQL repository.

The CodeQL CLI includes a command to test query help and render the content as markdown, so that you can easily preview the content in your IDE. Use the command to validate query help files before uploading them to the CodeQL repository or sharing them with other users. From CodeQL CLI 2.7.1 onwards, you can also include the markdown-rendered query help in SARIF files generated during CodeQL analyses so that the query help can be displayed in the code scanning UI. For more information, see "Analyzing your code with CodeQL queries."


  • The query help (.qhelp) file must have an accompanying query (.ql) file with an identical base name.
  • The query help file should follow the standard structure and style for query help documentation. For more information, see the Query help style guide in the CodeQL repository.

Running codeql generate query-help

You can test query help files by running the following command:

codeql generate query-help <qhelp|query|dir|suite> --format=<format> [--output=<dir|file>]

where <qhelp|query|dir|suite> is one of:

  • the path to a .qhelp file.
  • the path to a .ql file.
  • the path to a directory containing queries and query help files.
  • the path to a query suite, or the name of a well-known query suite for a CodeQL pack. For more information, see "Creating CodeQL query suites."

You must specify a --format option, which defines how the query help is rendered. Currently, you must specify markdown to render the query help as markdown.

The --output option defines a file path where the rendered query help will be saved.

  • For directories containing .qhelp files or a query suites defining one or more .qhelp files, you must specify an --output directory. Filenames within the output directory will be derived from the .qhelp file names.
  • For single .qhelp or .ql files, you may specify an --output option. If you don’t specify an output path, the rendered query help is written to stdout.

For full details of all the options you can use when testing query help files, see "generate query-help."


When you run the command, CodeQL attempts to render each .qhelp file that has an accompanying .ql file. For single files, the rendered content will be printed to stdout if you don’t specify an --output option. For all other use cases, the rendered content is saved to the specified output path.

By default, the CodeQL CLI will print a warning message if:

  • Any of the query help is invalid, along with a description of the invalid query help elements
  • Any .qhelp files specified in the command don’t have the same base name as an accompanying .ql file
  • Any .ql files specified in the command don’t have the same base name as an accompanying .qhelp file

You can tell the CodeQL CLI how to handle these warnings by including a --warnings option in your command. For more information, see "generate query-help."

Further reading