| # Code scanning query tables | |
| This nascent pipeline creates autogenerated documentation docs.github.com from the query suites included with the [CodeQL bundle](https://github.com/github/codeql-action/releases). | |
| The pipeline is used to generate Markdown tables that are stored in reusable files and used in article pages on the docs.github.com site. | |
| ## How does it work | |
| ```mermaid | |
| --- | |
| title: "Process for generating Code scanning query tables" | |
| --- | |
| flowchart TB | |
| accDescr: A flow chart describing how the automation generates documentation for code scanning queries. | |
| start([Start]) --> checkout[Checkout the codeql repository] | |
| start --- download[Download the CodeQL CLI] | |
| checkout --- query-suites[fa:fa-file Query suites *.qls] | |
| query-suites ---> generate[Generate tables:src/code-scanning/scripts/generate-code-scanning-query-lists.ts] | |
| download --- codeql-cli[CodeQL CLI: codeql.exe] | |
| codeql-cli --> generate | |
| generate --- markdown[fa:fa-file Reusable files *.md] | |
| markdown --> pr[Generate a PR overwriting:data/reusables/code-scanning/codeql-query-tables/*.md] | |
| pr --> finish([End]) | |
| %% Define styles | |
| classDef start fill:#1AAC9D, color:white | |
| classDef action fill:#6557F6, color:white | |
| classDef finish fill:#F8C324, color:white | |
| classDef file fill:#ddd | |
| %% Assign styles | |
| class start start; | |
| class finish finish; | |
| class checkout,download,generate,pr action; | |
| class markdown,query-suites,codeql-cli file; | |
| ``` | |
| A [workflow](.github/workflows/generate-code-scanning-query-lists.yml) is used to trigger the automation of the code scanning query tables documentation. The workflow is manually triggered by a member of the GitHub Docs team approximately every two weeks to align to releases of the CodeQL CLI. The workflow takes an input parameter that specifies the branch to pull the source files from in the semmle-code repo. If the branch input is omitted, the workflow will default to the `main` branch. | |
| The workflow runs the `npm run generate-code-scanning-query-list` script, which generates Markdown files under `data/reusables/code-scanning/codeql-query-tables`. | |
| The workflow automatically creates a new pull request with the changes and the label `codeql-query-tables`. | |
| ## Local development | |
| To run the pipeline locally, see the comments in the [script](scripts/generate-code-scanning-query-list.ts). | |
| ## Content team | |
| The content writers can use the reusables in any content article. They have no need to make any changes to the script unless additional built-in query suites are added. | |
| ## How to get help | |
| ### For workflow and script problems | |
| Slack: `#docs-engineering` | |
| Repo: `github/docs-engineering` | |
| ### For CodeQL repository and CLI problems | |
| Slack: `#code-scanning-internal-dx` | |
| Repo: `github/code-scanning-internal-dx-team` | |