This pipeline creates autogenerated documentation for docs.github.com from the query suites included with the CodeQL bundle.

The pipeline generates Markdown tables that are stored in reusable files and used in article pages on the docs.github.com site.

There are two types of query table generators:

1. Security queries (generate-code-scanning-query-list.ts) - generates tables for security-related queries from the code-scanning and security-extended suites, including CWE information and autofix support.
2. Code quality queries (generate-code-quality-query-list.ts) - generates tables for code quality queries from the code-quality suite, showing query categories (reliability, maintainability).

---
title: "Process for generating CodeQL query tables"
---
flowchart TB

accDescr: A flow chart describing how the automation generates documentation for CodeQL queries.

    start([Start]) --> checkout[Checkout the codeql repository]
    start --> download[Download the CodeQL CLI]

    checkout --> security-suites[fa:fa-file Security query suites *.qls]
    checkout --> quality-suites[fa:fa-file Quality query suites *.qls]

    security-suites --> generate-security[Generate security tables]
    quality-suites --> generate-quality[Generate quality tables]

    download --> codeql-cli[CodeQL CLI: codeql.exe]
    codeql-cli --> generate-security
    codeql-cli --> generate-quality

    generate-security --> security-markdown[fa:fa-file Security reusables *.md]
    generate-quality --> quality-markdown[fa:fa-file Quality reusables *.md]

    security-markdown --> merge[Merge artifacts]
    quality-markdown --> merge

    merge --> pr[Generate a PR with both:<br/>data/reusables/code-scanning/codeql-query-tables/*.md<br/>data/reusables/code-quality/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-security,generate-quality,merge,pr action;
    class security-markdown,quality-markdown,security-suites,quality-suites,codeql-cli file;

A workflow is used to trigger the automation of the CodeQL 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 codeql repo. If the branch input is omitted, the workflow will default to the main branch.

The workflow runs two scripts in parallel:

• npm run generate-code-scanning-query-list - generates security query tables under data/reusables/code-scanning/codeql-query-tables/
• npm run generate-code-quality-query-list - generates code quality query tables under data/reusables/code-quality/codeql-query-tables/

The workflow automatically creates a new pull request with changes from both scripts and the label codeql-query-tables.

To run the pipeline locally, see the comments in the scripts:

• Security queries: generate-code-scanning-query-list.ts
• Code quality queries: generate-code-quality-query-list.ts

The content writers can use the reusables in any content article. They have no need to make any changes to the scripts unless additional built-in query suites are added.

For security queries, reusables are stored in data/reusables/code-scanning/codeql-query-tables/. For code quality queries, reusables are stored in data/reusables/code-quality/codeql-query-tables/.

Slack: #docs-engineering Repo: github/docs-engineering

Slack: #code-scanning-engine-quality Repo: github/code-scanning-engine-quality-team