hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-06-16 10:21:09 +02:00
Code Issues Packages Projects Releases Wiki Activity

add procedural information for publishing and using CodeQL packs

Browse Source
This commit is contained in:
Ethan P
2021-07-20 23:21:36 -04:00
parent e586765cbe
commit 0eb2f903a3
2 changed files with 77 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/codeql/codeql-cli/creating-and-working-with-codeql-packs.rst
View File

@@ -9,7 +9,7 @@ You can use CodeQL packs to create, share, depend on, and run CodeQL queries and
Note
The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only in the GitHub Package Registry (GHPR).
The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only in the GitHub Package Registry (GHPR). You must use version 2.5.8 or later of the CodeQL CLI to use the CodeQL package manager.
About CodeQL packs and the CodeQL CLI package manager
-----------------------------------------------------
@@ -55,8 +55,18 @@ You can add dependencies on CodeQL packs using the command ``codeql pack add``.
The version number is optional. If you leave off the version number, the latest version will be added.
This command updates the ``qlpack.yml`` file with the requested dependencies and downloads them into the package cache.
You can also manually edit the ``qlpack.yml`` file to include dependencies and install the dependencies with the command:
::
codeql pack install
This command downloads all dependencies to the shared cache on the local disk.
.. pull-quote::
Note
Running the ``codeql pack add`` and ``codeql pack install`` commands will generate or update the ``qlpack.lock.yml`` file. This file should be checked-in to version control. ``qlpack.lock.yml`` contains the precise version numbers used by the pack.

67
docs/codeql/codeql-cli/publishing-and-using-codeql-packs.rst
View File

@@ -9,4 +9,69 @@ You can publish your own CodeQL packs and use packs published by other people.
Note
The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only in the GitHub Package Registry (GHPR).
The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only in the GitHub Package Registry (GHPR). You must use version 2.5.8 or later of the CodeQL CLI to use the CodeQL package manager.
TODO: conceptual information
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.
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:
default-suite: # a query-suite file that has been inlined
- query:
default-suite-file: default-queries.qls # a pointer to a query-suite in this pack
license:
dependencies:
- ``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.
- Only one of ``default-suite`` or ``default-suite-file`` is allowed. Both options define a default query suite to be run.
Running ``codeql pack publish``
-------------------------------
When you are ready to upload a pack to a shared repository, you can run the following command:
::
codeql pack publish
The published package will appear in the packages section of your GitHub organization.
Running ``codeql pack download <scope>/<pack>``
-----------------------------------------------
To run a pack that someone else has created, you must 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 are creating.
- ``@x.x.x``: an optional version number. If omitted, the latest version will be downloaded.
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 --allow-packs <scope>/<pack>@x.x.x
- ``<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.
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 --allow-packs <scope>/<pack> <scope>/<other-pack>