Merge pull request #10344 from github/aeisenberg/registries-in-workspace

Add information about the `registries` block in `codeql-workspace.yml`

Author: aeisenberg

docs/codeql/codeql-cli/about-codeql-workspaces.rst

@@ -14,14 +14,15 @@ In most cases, you should store the CodeQL workspace and the CodeQL packs contai
 The ``codeql-workspace.yml`` file
 ---------------------------------
 
-A CodeQL workspace is defined by a ``codeql-workspace.yml`` yaml file. This file contains a ``provide`` block, and optionally an ``ignore`` block.
+A CodeQL workspace is defined by a ``codeql-workspace.yml`` yaml file. This file contains a ``provide`` block, and optionally ``ignore`` and ``registries`` blocks.
 
 * The ``provide`` block contains a list of glob patterns that define the CodeQL packs that are available in the workspace.
 * The ``ignore`` block contains a list of glob patterns that define CodeQL packs that are not available in the workspace.
+* The ``registries`` block contains a list of GHES URLs and package patterns that control which container registry is used for publishing CodeQL packs. For more information, see :ref:`Working with CodeQL packs on GitHub Enterprise Server <working-with-codeql-packs-on-ghes>`.
 
 Each entry in the ``provide`` or ``ignore`` section must map to the location of a ``qlpack.yml`` file. All glob patterns are defined relative to the directory that contains the workspace file. For a list of patterns accepted in this file, see" `@actions/glob <https://github.com/actions/toolkit/tree/main/packages/glob#patterns>`__ .
 
-For example, the following ``codeql-workspace.yml`` file defines a workspace that contains all the CodeQL packs recursively found in the ``codeql-packs`` directory, except for the packs in the ``experimental`` directory:
+For example, the following ``codeql-workspace.yml`` file defines a workspace that contains all the CodeQL packs recursively found in the ``codeql-packs`` directory, except for the packs in the ``experimental`` directory. The ``registries`` block specifies that ``codeql/*`` packs should be downloaded from https://ghcr.io/v2/, which is GitHub's default container registry. All other packs should be downloaded from and published to the regsitry at ``GHE_HOSTNAME``.
 
 .. code-block:: yaml
 
@@ -30,6 +31,13 @@ For example, the following ``codeql-workspace.yml`` file defines a workspace tha
     ignore:
       - "*/codeql-packs/**/experimental/**/qlpack.yml"
 
+    registries:
+     - packages: 'codeql/*'
+       url: https://ghcr.io/v2/
+
+     - packages: '*'
+       url: https://containers.GHE_HOSTNAME/v2/
+
 To verify that your ``codeql-workspace.yml`` file includes the CodeQL packs that you expect, run the ``codeql pack ls`` command in the same directory as your workspace. The result of the command is a list of all CodeQL packs in the workspace.
 
 .. _source-dependencies:

docs/codeql/codeql-cli/publishing-and-using-codeql-packs.rst

@@ -74,6 +74,8 @@ The ``analyze`` command will run the default suite of any specified CodeQL packs
 
    codeql <database> analyze <scope>/<pack> <scope>/<other-pack>
 
+.. _working-with-codeql-packs-on-ghes:
+
 Working with CodeQL packs on GitHub Enterprise Server
 -----------------------------------------------------
 
@@ -91,13 +93,17 @@ For example, the following ``qlconfig.yml`` file associates all packs with the C
 .. code-block:: yaml
 
    registries:
-   - packages: 'codeql/*'
+   - 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.
+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.