mirror of
https://github.com/github/codeql.git
synced 2025-12-22 03:36:30 +01:00
132 lines
7.2 KiB
ReStructuredText
132 lines
7.2 KiB
ReStructuredText
.. _publishing-and-using-codeql-packs:
|
|
|
|
Publishing and using CodeQL packs
|
|
=================================
|
|
|
|
You can publish your own CodeQL packs and use packs published by other people.
|
|
|
|
.. include:: ../reusables/beta-note-package-management.rst
|
|
|
|
Configuring the ``qlpack.yml`` file before publishing
|
|
-----------------------------------------------------
|
|
|
|
You can check and modify the configuration details of your CodeQL pack prior to publishing. Open the ``qlpack.yml`` file in your preferred text editor.
|
|
|
|
.. code-block:: none
|
|
|
|
library: # set to true if the pack is a library. Set to false or omit for a query pack
|
|
name: <scope>/<pack>
|
|
version: <x.x.x>
|
|
description: <Description to publish with the package>
|
|
default-suite: # optional, one or more queries in the pack to run by default
|
|
- query: <relative-path>/query-file>.ql
|
|
default-suite-file: default-queries.qls # optional, a pointer to a query-suite in this pack
|
|
license: # optional, the license under which the pack is published
|
|
dependencies: # map from CodeQL pack name to version range
|
|
|
|
- ``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.
|
|
- A maximum of one of ``default-suite`` or ``default-suite-file`` 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.
|
|
|
|
Running ``codeql pack publish``
|
|
-------------------------------
|
|
|
|
When 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:
|
|
|
|
::
|
|
|
|
codeql pack publish
|
|
|
|
The published package will be displayed in the packages section of GitHub organization specified by the scope in the ``qlpack.yml`` file.
|
|
|
|
Running ``codeql pack download <scope>/<pack>``
|
|
-----------------------------------------------
|
|
|
|
To run a pack that someone else has created, you must first download it by running the following command:
|
|
|
|
::
|
|
|
|
codeql pack download <scope>/<pack>@x.x.x
|
|
|
|
- ``<scope>``: the name of the GitHub organization that you will download from.
|
|
- ``<pack>``: the name for the pack that you want to download.
|
|
- ``@x.x.x``: an optional version number. If omitted, the latest version will be downloaded.
|
|
|
|
This command accepts arguments for multiple packs.
|
|
|
|
Using a CodeQL pack to analyze a CodeQL database
|
|
------------------------------------------------
|
|
|
|
To analyze a CodeQL database with a CodeQL pack, run the following command:
|
|
|
|
::
|
|
|
|
codeql database analyze <database> <scope>/<pack>@x.x.x:<path>
|
|
|
|
- ``<database>``: the CodeQL database to be analyzed.
|
|
- ``<scope>``: the name of the GitHub organization that the pack is published to.
|
|
- ``<pack>``: the name for the pack that you are using.
|
|
- ``@x.x.x``: an optional version number. If omitted, the latest version will be used.
|
|
- ``:<path>``: an optional path to a query, directory, or query suite. If omitted, the pack's default query suite will be used.
|
|
|
|
The ``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:
|
|
|
|
::
|
|
|
|
codeql <database> analyze <scope>/<pack> <scope>/<other-pack>
|
|
|
|
.. _working-with-codeql-packs-on-ghes:
|
|
|
|
Working with CodeQL packs on GitHub Enterprise Server
|
|
-----------------------------------------------------
|
|
|
|
.. pull-quote::
|
|
|
|
Note
|
|
|
|
The Container registry for GitHub Enterprise Server supports CodeQL query packs from GitHub Enterprise Server 3.6 onward.
|
|
|
|
By default, the CodeQL CLI expects to download CodeQL packs from and publish packs to the Container registry on GitHub.com. However, you can also work with CodeQL packs in a Container registry on GitHub Enterprise Server 3.6, and later, by creating a ``qlconfig.yml`` file to tell the CLI which Container registry to use for each pack.
|
|
|
|
Create a ``~/.codeql/qlconfig.yml`` file using your preferred text editor, and add entries to specify which registry to use for one or more package name patterns.
|
|
For example, the following ``qlconfig.yml`` file associates all packs with the Container registry for the GitHub Enterprise Server at ``GHE_HOSTNAME``, except packs matching ``codeql/*``, which are associated with the Container registry on GitHub.com:
|
|
|
|
.. code-block:: yaml
|
|
|
|
registries:
|
|
- packages:
|
|
- 'codeql/*'
|
|
- 'other-org/*'
|
|
url: https://ghcr.io/v2/
|
|
- packages: '*'
|
|
url: https://containers.GHE_HOSTNAME/v2/
|
|
|
|
The CodeQL CLI will determine which registry to use for a given package name by finding the first item in the ``registries`` list with a ``packages`` property that matches that package name.
|
|
This means that you'll generally want to define the most specific package name patterns first. The ``packages`` property may be a single package name, a glob pattern, or a YAML list of package names and glob patterns.
|
|
|
|
The ``registries`` list can also be placed inside of a ``codeql-workspace.yml`` file. Doing so will allow you to define the registries to be used within a specific workspace, so that it can be shared amongst other CodeQL users of the workspace. The ``registries`` list in the ``codeql-workspace.yml`` will be merged with and take precedence over the list in the global ``qlconfig.yml``. For more information about ``codeql-workspace.yml``, see :ref:`About CodeQL workspaces <about-codeql-workspaces>`.
|
|
|
|
You can now use ``codeql pack publish``, ``codeql pack download``, and ``codeql database analyze`` to manage packs on GitHub Enterprise Server.
|
|
|
|
Authenticating to GitHub Container registries
|
|
---------------------------------------------
|
|
|
|
You can publish packs and download private packs by authenticating to the appropriate GitHub Container registry.
|
|
|
|
You can authenticate to the Container registry on GitHub.com in two ways:
|
|
|
|
1. Pass the ``--github-auth-stdin`` option to the CodeQL CLI, then supply a GitHub Apps token or personal access token via standard input.
|
|
2. Set the ``GITHUB_TOKEN`` environment variable to a GitHub Apps token or personal access token.
|
|
|
|
Similarly, you can authenticate to a GHES Container registry, or authenticate to multiple registries simultaneously (for example, to download or run private packs from multiple registries) in two ways:
|
|
|
|
1. Pass the ``--registries-auth-stdin`` option to the CodeQL CLI, then supply a registry authentication string via standard input.
|
|
2. Set the ``CODEQL_REGISTRIES_AUTH`` environment variable to a registry authentication string.
|
|
|
|
A registry authentication string is a comma-separated list of ``<registry-url>=<token>`` pairs, where ``registry-url`` is a GitHub Container registry URL, such as ``https://containers.GHE_HOSTNAME/v2/``, and ``token`` is a GitHub Apps token or personal access token for that GitHub Container registry.
|
|
This ensures that each token is only passed to the Container registry you specify.
|
|
For instance, the following registry authentication string specifies that the CodeQL CLI should authenticate to the Container registry on GitHub.com using the token ``<token1>`` and to the Container registry for the GHES instance at ``GHE_HOSTNAME`` using the token ``<token2>``:
|
|
|
|
.. code-block:: none
|
|
|
|
https://ghcr.io/v2/=<token1>,https://containers.GHE_HOSTNAME/v2/=<token2>
|