Text of github.blog › engineering › how-github-uses-codeql-to-secure-github as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

How GitHub uses CodeQL to secure GitHub - The GitHub Blog

Brandon Stewart · @boveus February 12, 2025 | 11 minutes Share: GitHub’s Product Security Engineering team writes code and implements tools that help secure the code that powers GitHub. We use GitHub Advanced Security (GHAS) to discover, track, and remediate vulnerabilities and enforce secure coding standards at scale. One tool we rely heavily on to analyze our code at scale is CodeQL . CodeQL is GitHub’s static analysis engine that powers automated security analyses.

You can use it to query code in much the same way you would query a database. It provides a much more robust way to analyze code and uncover problems than an old-fashioned text search through a codebase. The following post will detail how we use CodeQL to keep GitHub secure and how you can apply these lessons to your own organization. You will learn why and how we use: Custom query packs (and how we create and manage them).

Custom queries. Variant analysis to uncover potentially insecure programming practices. Enabling CodeQL at scale We employ CodeQL in a variety of ways at GitHub. Default setup with the default and security-extended query suites Default setup with the default and security-extended query suites meets the needs of the vast majority of our over 10,000 repositories. With these settings, pull requests automatically get a security review from CodeQL.

Advanced setup with a custom query pack A few repositories, like our large Ruby monolith, need extra special attention, so we use advanced setup with a query pack containing custom queries to really tailor to our needs. Multi-repository variant analysis (MRVA) To conduct variant analysis and quick auditing, we use MRVA. We also write custom CodeQL queries to detect code patterns that are either specific to GitHub’s codebases or patterns we want a security engineer to manually review.

The specific custom Actions workflow step we use on our monolith is pretty simple. It looks like this: - name: Initialize CodeQL uses: github/codeql-action/init@v3 with: languages: ${{ matrix.language }} config-file: ./.github/codeql/${{ matrix.language }}/codeql-config.yml Our Ruby configuration is pretty standard, but advanced setup offers a variety of configuration options using custom configuration files . The interesting part is the packs option, which is how we enable our custom query pack as part of the CodeQL analysis.

This pack contains a collection of CodeQL queries we have written for Ruby, specifically for the GitHub codebase. So, let’s dive deeper into why we did that—and how! Publishing our CodeQL query pack Initially, we published CodeQL query files directly to the GitHub monolith repository, but we moved away from this approach for several reasons: It required going through the production deployment process for each new or updated query.

Queries not included in a query pack were not pre-compiled , which slowed down CodeQL analysis in CI. Our test suite for CodeQL queries ran as part of the monolith’s CI jobs. When a new version of the CodeQL CLI was released, it sometimes caused the query tests to fail because of changes in the query output, even when there were no changes to the code in the pull request. This often led to confusion and frustration among engineers, as the failure wasn’t related to their pull request changes.

By switching to publishing a query pack to GitHub Container Registry (GCR) , we’ve simplified our process and eliminated many of these pain points, making it easier to ship and maintain our CodeQL queries. So while it’s possible to deploy custom CodeQL query files directly to a repository, we recommend publishing CodeQL queries as a query pack to the GCR for easier deployment and faster iteration. Creating our query pack When setting up our custom query pack , we faced several considerations, particularly around managing dependencies like the ruby-all package.

To ensure our custom queries remain maintainable and concise, we extend classes from the default query suite , such as the ruby-all library. This allows us to leverage existing functionality rather than reinventing the wheel, keeping our queries concise and maintainable. However, changes to the CodeQL library API can introduce breaking changes, potentially deprecating our queries or causing errors. Since CodeQL runs as part of our CI, we wanted to minimize the chance of this happening, as this can lead to frustration and loss of trust from developers.

We develop our queries against the latest version of the ruby-all package, ensuring we’re always working with the most up-to-date functionality. To mitigate the risk of breaking changes affecting CI, we pin the ruby-all version when we’re ready to release, locking it in the codeql-pack.lock.yml file . This guarantees that when our queries are deployed, they will run with the specific version of ruby-all we’ve tested, avoiding potential issues from unintentional updates.

Here’s how we manage this setup: In our qlpack.yml, we set the dependency to use the latest version of ruby-all During development, this configuration pulls in the latest version ) of ruby-all when running codeql pack init , ensuring we’re always up to date. // Our custom query pack's qlpack.yml library: false name: github/internal-ruby-codeql version: 0.2.3 extractor: 'ruby' dependencies: codeql/ruby-all: "*" tests: 'test' description: "Ruby CodeQL queries used internally at GitHub" Before releasing, we lock the version in the codeql-pack.lock.yml file, specifying the exact version to ensure stability and prevent issues in CI. // Our custom query pack's codeql-pack.lock.yml lockVersion: 1.0.0 dependencies: ... codeql/ruby-all: version: 1.0.6 This approach allows us to balance developing against the latest features of the ruby-all package while ensuring stability when we release.

We also have a set of CodeQL unit tests that exercise our queries against sample code snippets, which helps us quickly determine if any query will cause errors before we publish our pack. These tests are run as part of the CI process in our query pack repository, providing an early check for issues. We strongly recommend writing unit tests for your custom CodeQL queries to ensure stability and reliability. Altogether, the basic flow for releasing new CodeQL queries via our pack is as follows: Open a pull request with the new query.

Write unit tests for the new query. Merge the pull request. Increment the pack version in a new pull request. Run codeql pack init to resolve dependencies. Correct unit tests as needed. Publish the query pack to the GitHub Container Registry (GCR). Repositories with the query pack in their config will start using the updated queries. We have found this flow balances our team’s development experience while ensuring stability in our published query pack.

Configuring our repository to use our custom query pack We won’t provide a general recommendation on configuration here, given that it ultimately depends on how your organization deploys code. We opted against locking our pack to a particular version in our CodeQL configuration file (see above). Instead, we chose to manage our versioning by publishing the CodeQL package in GCR. This results in the GitHub monolith retrieving the latest published version of the query pack.

To roll back changes, we simply have to republish the package. In one instance, we released a query that had a high number of false positives and we were able to publish a new version of the pack that removed that query in less than 15 minutes. This is faster than the time it would have taken us to merge a pull request on the monolith repository to roll back the version in the CodeQL configuration file. One of the problems we encountered with publishing the query pack in GCR was how to easily make the package available to multiple repositories within our enterprise.

There are several approaches we explored. Grant access permissions for individual repositories. On the package management page,

The rest of this page is on the live site.