The latest release of the CodeQL CLI supports including markdown-rendered query help in SARIF files so that the help text can be viewed in the code scanning UI. This functionality is now available for code scanning on GitHub.com and will be available in GitHub Enterprise Server 3.4.
The CodeQL query help text is displayed in the code scanning UI whenever the query generates an alert. The query help explains the problem in more detail, and shows examples of vulnerable and fixed code. Until now, code scanning only displayed the query help for alerts generated by the default CodeQL queries. With the release of CodeQL CLI 2.7.1, the query help for your own custom queries will be uploaded to GitHub and displayed in code scanning.
Writing query help for custom CodeQL queries
When you write your own queries, we recommend that you write a query help file so that other users can properly understand the impact an alert has on the security of their code. For custom query help in your repository there are no restrictions on the content, but we recommend that you follow the Query help style guide to make the help text as useful as possible.
You should write query help for custom queries in your repository in a markdown file alongside the corresponding query. CodeQL code scanning looks for query help files written in markdown that share the same name as the corresponding query file. For example, if your query file is MyCustomQuery.ql, the query help file should be named MyCustomQuery.md.
For users of 3rd party CI/CD systems
When using CodeQL with GitHub Actions, the query help will automatically be imported from markdown files that are stored alongside the corresponding custom queries. The query help is inserted into SARIF files generated during the analysis step and made available in the code scanning UI.
If you use a different CI/CD system, you have to add the --sarif-add-query-help flag to the codeql database analyze command to include the query help in your SARIF results files. For more information, see Analyzing databases with the CodeQL CLI.