{"meta":{"title":"Creating and working with CodeQL packs","intro":"You can use CodeQL packs to create, share, depend on, and run CodeQL queries and libraries.","product":"Security and code quality","breadcrumbs":[{"href":"/en/code-security","title":"Security and code quality"},{"href":"/en/code-security/tutorials","title":"Tutorials"},{"href":"/en/code-security/tutorials/customize-code-scanning","title":"Customize code scanning"},{"href":"/en/code-security/tutorials/customize-code-scanning/creating-and-working-with-codeql-packs","title":"Creating and working with CodeQL packs"}],"documentType":"article"},"body":"# Creating and working with CodeQL packs\n\nYou can use CodeQL packs to create, share, depend on, and run CodeQL queries and libraries.\n\n## About CodeQL packs and the CodeQL CLI\n\nCodeQL packs are used to create, share, depend on, and run CodeQL queries and libraries.\n\nYou can use the `pack` command in the CodeQL CLI to create CodeQL packs, add dependencies to packs, and install or update dependencies. You can also publish and download CodeQL packs using the `pack` command.\n\n## Creating a CodeQL pack\n\nYou can create a CodeQL pack by running the following command from the checkout root of your project:\n\n```shell\ncodeql pack init <scope>/<pack>\n```\n\nYou must specify:\n\n* `<scope>`: the name of the GitHub organization or user account that you will publish to.\n\n* `<pack>`: the name for the pack that you are creating.\n\nThe `codeql pack init` command creates the directory structure and configuration files for a CodeQL pack. By default, the command creates a query pack. If you want to create a library pack, you must edit the `qlpack.yml` file to explicitly declare the file as a library pack by including the `library:true` property.\n\n## Creating a CodeQL model pack\n\n> \\[!NOTE]\n> CodeQL model packs are currently in public preview and subject to change. Model packs are supported for C/C++, C#, Java/Kotlin, Python, Ruby, and Rust analysis.\n>\n> The CodeQL model editor in the CodeQL extension for Visual Studio Code supports modeling dependencies for  C#, Java/Kotlin, Python, and Ruby.\n\nModel packs can be used to expand code scanning analysis to recognize libraries and frameworks that are not supported by default. Model packs use data extensions, which are implemented as YAML and describe how to add data for new dependencies. When a model pack is specified, the data extensions in that pack will be added to the code scanning analysis automatically. For more information about CodeQL model packs and data extensions, see [Using the CodeQL model editor](/en/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor).\n\nA model pack is a CodeQL pack with the following characteristics in the `qlpack.yml` file:\n\n* It defines `library: true`.\n* It has no dependencies.\n* It has one or more `extensionTargets`.\n* It has a `dataExtensions` property that points to one or more data extension files.\n\nA model pack will inject its specified data extensions into each query pack that is named in `extensionTargets`, if it falls within the specified version range. For example:\n\n```yaml\nname: my-repo/my-java-model-pack\nversion: 1.2.3\nextensionTargets:\n  codeql/java-all: ~1.2.3\n  codeql/util: ~4.5.6\ndataExtensions:\n  - models/**/*.yml\n```\n\nIn this example, the model pack will inject all the data extensions in `models/**/` into a `codeql/java-all` query pack that is at a version from `1.2.3` up to and including `1.3.0`, and a `codeql/util` query pack that is at a version from `4.5.6` up to and including `4.6.0`. For more information, see [Using semantic versioning](https://docs.npmjs.com/about-semantic-versioning#using-semantic-versioning-to-specify-update-types-your-package-can-accept) in the npm documentation and the [Semantic versioning specification](https://semver.org/).\n\nOnce you've created a model pack, you can publish it in the same way as other CodeQL packs. For more information, see [Publishing and using CodeQL packs](/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs). You can then use published model packs in a code scanning analysis with the `--model-packs` option. For more information, see [Customizing analysis with CodeQL packs](/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies).\n\n## Adding and installing dependencies on a CodeQL pack\n\n> \\[!NOTE]\n> This is only supported for CodeQL query and library packs.\n\nYou can add dependencies on CodeQL packs using the command `codeql pack add`. You must specify the scope, name, and (optionally) a compatible version range.\n\n```shell\ncodeql pack add <scope>/<name>@x.x.x <scope>/<other-name>\n```\n\nIf you don’t specify a version range, the latest version will be added. Otherwise, the latest version that satisfies the requested range will be added.\n\nThis command updates the `qlpack.yml` file with the requested dependencies and downloads them into the package cache. Please note that this command will reformat the file and remove all comments.\n\nYou can also manually edit the `qlpack.yml` file to include dependencies and install the dependencies with the command:\n\n```shell\ncodeql pack install\n```\n\nThis command downloads all dependencies to the shared cache on the local disk.\n\n> \\[!NOTE]\n>\n> * Running the `codeql pack add` and `codeql pack install` commands will generate or update the `codeql-pack.lock.yml` file. This file should be checked-in to version control. The `codeql-pack.lock.yml` file contains the precise version numbers used by the pack. For more information, see [About codeql-pack.lock.yml files](/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs##about-codeql-packlockyml-files).\n> * By default `codeql pack install` will install dependencies from the Container registry on GitHub.com. You can install dependencies from a GitHub Enterprise Server Container registry by creating a `qlconfig.yml` file. For more information, see [Publishing and using CodeQL packs](/en/enterprise-server@3.20/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs) in the GitHub Enterprise Server documentation.\n\n## Organizing a CodeQL pack's directory structure\n\nA CodeQL pack must contain a file called `qlpack.yml` in its root directory. In the `qlpack.yml` file, the `name:` field must have a value that follows the format of `<scope>/<pack>`, where `<scope>` is the GitHub organization or user account that the pack will be published to and `<pack>` is the name of the pack.\n\nAdditionally, query packs and library packs with CodeQL tests contain a `codeql-pack.lock.yml` file that contains the resolved dependencies of the pack. This file is generated during a call to the `codeql pack install` command, is not meant to be edited by hand, and should be added to your version control system.\n\nThe other files and directories within the pack should be logically organized. For example, typically:\n\n* Queries are organized into directories for specific categories.\n* Queries for specific products, libraries, and frameworks are organized into\n  their own top-level directories.\n\n## Customizing a downloaded CodeQL pack\n\nThe recommended way to experiment with changes to a pack is to clone the repository containing its source code.\n\nIf no source repository is available and you need to base modifications on a pack downloaded from the Container registry, be aware that these packs are not intended to be modified or customized after downloading, and their format may change in the future without much notice. We recommend taking the following steps after downloading a pack if you need to modify the content:\n\n* Change the pack *name* in `qlpack.yml` so you avoid confusion with results from the unmodified pack.\n\n* Remove all files named `*.qlx` anywhere in the unpacked directory structure. These files contain precompiled versions of the queries, and in some situations CodeQL will use them in preference to the QL source you have modified."}