{"meta":{"title":"Publishing and using CodeQL packs","intro":"Share or download a CodeQL pack, then analyze your CodeQL database.","product":"Security and code quality","breadcrumbs":[{"href":"/en/code-security","title":"Security and code quality"},{"href":"/en/code-security/how-tos","title":"How-tos"},{"href":"/en/code-security/how-tos/find-and-fix-code-vulnerabilities","title":"Find and fix code vulnerabilities"},{"href":"/en/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line","title":"Scan from the command line"},{"href":"/en/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/publish-and-use-packs","title":"Publish and use packs"}],"documentType":"article"},"body":"# Publishing and using CodeQL packs\n\nShare or download a CodeQL pack, then analyze your CodeQL database.\n\n## Authenticating to GitHub Container registries\n\nYou can publish packs and download private packs by authenticating to the appropriate GitHub Container registry.\n\nYou can authenticate to the Container registry in two ways:\n\n1. Pass the `--github-auth-stdin` option to the CodeQL CLI, then supply a GitHub Apps token or personal access token via standard input.\n2. Set the `GITHUB_TOKEN` environment variable to a GitHub Apps token or personal access token.\n\n## Publishing your CodeQL pack\n\nTo share your CodeQL pack with other people, you can publish it to the Container registry.\n\n### Configuring the `qlpack.yml` file before publishing\n\nYou can check and modify the configuration details of your CodeQL pack prior to publishing. Open the `qlpack.yml` file in your preferred text editor.\n\n```yaml\nlibrary: # set to true if the pack is a library. Set to false or omit for a query pack\nname: <scope>/<pack>\nversion: <x.x.x>\ndescription: <Description to publish with the package>\ndefaultSuite: # optional, one or more queries in the pack to run by default\n    - query: <relative-path>/query-file>.ql\ndefaultSuiteFile: default-queries.qls # optional, a pointer to a query-suite in this pack\nlicense: # optional, the license under which the pack is published\ndependencies: # map from CodeQL pack name to version range\n```\n\n* `name:` must follow the `<scope>/<pack>` format, where `<scope>` is the GitHub organization that you will publish to and `<pack>` is the name for the pack.\n\n* A maximum of one of `defaultSuite` or `defaultSuiteFile` is allowed. These are two different ways to define a default query suite to be run, the first by specifying queries directly in the qlpack.yml file and the second by specifying a query suite in the pack.\n\n### Running `codeql pack publish`\n\nWhen you are ready to publish a pack to the GitHub Container registry, you can run the following command in the root of the pack directory:\n\n```shell\ncodeql pack publish\n```\n\nThe published package will be displayed in the packages section of GitHub organization specified by the scope in the `qlpack.yml` file.\n\n> \\[!NOTE]\n> If you're publishing model packs to the GitHub Container registry in order to extend coverage to all repositories in an organization as part of a default setup configuration, then you need to ensure that repositories running code scanning can access those model packs. For more information, see [Editing your configuration of default setup](/en/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup) and [Configuring a package's access control and visibility](/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility).\n\n## Downloading an existing CodeQL pack\n\nTo run a pack that someone else has created, you must first download it by running the following command:\n\n```shell\ncodeql pack download <scope>/<pack>@x.x.x\n```\n\n* `<scope>`: the name of the GitHub organization that you will download from.\n* `<pack>`: the name for the pack that you want to download.\n* `@x.x.x`: an optional version number. If omitted, the latest version will be downloaded.\n\nThis command accepts arguments for multiple packs.\n\nIf you write scripts that specify a particular version number of a\nquery pack to download, keep in mind that when you update your version of\nCodeQL to a newer one, you may\nalso need to switch to a newer version of the query pack. Newer\nversions of CodeQL *may* provide\ndegraded performance when used with query packs that have been pinned\nto a very old version. For more information, see [CodeQL query packs reference](/en/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs#codeql-pack-compatibility).\n\n## Using a CodeQL pack to analyze a CodeQL database\n\nTo analyze a CodeQL database with a CodeQL pack, run the following command:\n\n```shell\ncodeql database analyze <database> <scope>/<pack>@x.x.x:<path>\n```\n\n* `<database>`: the CodeQL database to be analyzed.\n* `<scope>`: the name of the GitHub organization that the pack is published to.\n* `<pack>`: the name for the pack that you are using.\n* `@x.x.x`: an optional version number. If omitted, the latest version will be used.\n* `:<path>`: an optional path to a query, directory, or query suite. If omitted, the pack’s default query suite will be used.\n\nThe `analyze` command will run the default suite of any specified CodeQL packs. You can specify multiple CodeQL packs to be used for analyzing a CodeQL database. For example:\n\n```shell\ncodeql <database> analyze <scope>/<pack> <scope>/<other-pack>\n```\n\n> \\[!NOTE]\n> The `codeql pack download` command stores the pack it downloads in an internal location that is not intended for local modification. Unexpected (and hard to troubleshoot) behavior may result if the pack is modified after downloading. For more information about customizing packs, see [Creating and working with CodeQL packs](/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs)."}