Guide · Open source
How to use CodeQL: clone the repo, read the queries and run checks
Updated · written with AI from the project's own documentation and checked against our catalogue data
CodeQL is a way to write queries that search source code for patterns, such as security weaknesses. The github/codeql repository holds the standard CodeQL libraries and queries that GitHub uses in GitHub Advanced Security and its other application security products. This guide explains what the repository is, how to clone it, where to learn the language, and how to contribute, so you can read, run, or improve those checks.
CodeQLgithub/codeql · ★ 10.3k · MIT Install options & downloads Quick start
- 1Clone the repository. Run git clone https://github.com/github/codeql to get a local copy of the libraries and queries.
- 2Read the documentation. Start with the CodeQL language docs and the guides for the Visual Studio Code extension and the CodeQL CLI.
- 3Install the VS Code extension. Install the CodeQL for Visual Studio Code extension for syntax highlighting, IntelliSense and unit test support.
- 4Get the CodeQL CLI. Obtain the CodeQL CLI separately if you need command-line analysis, keeping in mind its separate licence.
- 5Explore the standard checks. Open the libraries and queries in the repository and study how they are structured.
- 6Contribute. Read CONTRIBUTING.md and the style guides, then open a pull request with your improvement.
What the github/codeql repository contains
This open source repository contains the standard CodeQL libraries and queries. These are the same building blocks that power GitHub Advanced Security and the other application security products GitHub offers its customers.
The repository is licensed under the MIT License. It is most useful if you want to study how the checks are written, run them, or contribute to them. It is not a finished scanning tool you can point at a project and run immediately.
- Standard CodeQL libraries: reusable code that queries build on.
- Standard checks: the queries GitHub uses in its security products.
- Licence: MIT for the code in this repository.
Clone the repository
Start by cloning the repository to your machine using the command from the README. This gives you a local copy of the libraries and queries so you can read and edit them.
The README describes the setup as clone-and-build, so the repository is the starting point for working with the code, not a packaged program.
git clone https://github.com/github/codeqlSet up Visual Studio Code and the CodeQL tools
To run queries, the README points to two tools: the CodeQL extension for Visual Studio Code and the CodeQL CLI. The extension gives you syntax highlighting, IntelliSense, code navigation for the QL language, and unit test support for testing CodeQL libraries and queries.
The CodeQL CLI is licensed separately. The README notes that if you want to use the CodeQL CLI to analyze closed-source code, you will need a separate commercial license.
- Visual Studio Code with the CodeQL for Visual Studio Code extension (optional, for running queries).
- CodeQL CLI (needed for command-line analysis, licensed separately).
- Use the repository's .vscode/tasks.json by selecting Terminal | Run Task... in Visual Studio Code, or running the Tasks: Run Task command from the command palette.
Learn the CodeQL language
Before editing queries, read the documentation. The README points to the CodeQL language documentation, guides for writing CodeQL in Visual Studio Code, and documentation for the CodeQL CLI.
Reading existing standard checks alongside the docs is a practical way to see how queries are organized and how shared libraries are used.
- CodeQL language docs at codeql.github.com/docs.
- CodeQL extension for Visual Studio Code documentation on docs.github.com.
- CodeQL CLI documentation on docs.github.com.
Contribute a change
The project welcomes contributions to the standard library and standard checks, including new checks and improvements to existing queries. Read the contributing guidelines before opening a pull request.
The repository also has style guides covering code formatting, query metadata, and query help documentation. Documentation contributions have their own guide in docs/codeql/CONTRIBUTING.md.
- Read CONTRIBUTING.md in the repository.
- Follow the style guides in the docs folder for formatting, query metadata and query help.
- Open a pull request with your change.
Compare CodeQL with other tools
CodeQL is one of several static analysis options. The README does not compare it with other tools, so choose based on your needs. Projects often compared with it include Semgrep, SonarQube, Bandit, and ESLint.
If you want a ready-made scan with little setup, this repository alone will not give you one. Use the CodeQL extension and CLI to run queries, and check their licensing terms before analyzing closed-source code.
What people use it for
- Studying how GitHub's standard security checks are written.
- Learning the QL language by reading real queries and libraries.
- Proposing a new check or an improvement to an existing query through a pull request.
- Using the Visual Studio Code extension to write and unit test CodeQL queries.
Frequently asked questions
Is CodeQL free?
The code in the github/codeql repository is licensed under the MIT License. The CodeQL CLI, including the CodeQL engine, is hosted in a different repository and is licensed separately. The README says that using the CLI to analyze closed-source code requires a separate commercial license.
Do I need a license to use CodeQL?
You do not need a separate license to read or contribute to this repository under MIT. The README says analyzing closed-source code with the CodeQL CLI needs a separate commercial license, and you should contact GitHub for details.
Is github/codeql a scanner I can run directly?
No. The README points to the CodeQL extension for Visual Studio Code and the CodeQL CLI for running queries. This repository holds the standard libraries and queries, so it is best for reading, running within those tools, or contributing.
How do I install CodeQL?
The README's install step is to clone the repository with git clone https://github.com/github/codeql. To run queries, it refers you to the CodeQL extension for Visual Studio Code and the CodeQL CLI, which are documented on docs.github.com and codeql.github.com.
How does CodeQL compare to Semgrep or SonarQube?
The README does not compare CodeQL with other tools. Semgrep, SonarQube, Bandit, and ESLint are commonly compared with it, so test a few on your own code and compare the results and setup effort before deciding.
Who should use this repository?
It suits security researchers who want to study or extend CodeQL queries, developers learning how queries are organized, contributors who want to improve standard checks, and teams using GitHub Advanced Security who want to understand its built-in checks.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this repository if you want to read, learn from, run within the CodeQL tools, or contribute to the standard CodeQL libraries and checks. If you want a finished scanner with no setup, or you need to analyze closed-source code with the CLI without a commercial licence, pick a different tool or check the licensing terms first.
Install options & downloads