Merge pull request #9585 from github/henrymercer/packaging-on-ghes

Docs: Document packaging support for CodeQL CLI 2.9.4+ on GHES 3.6+

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

@@ -68,3 +68,11 @@ This command downloads all dependencies to the shared cache on the local disk.
    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. The ``qlpack.lock.yml`` file contains the precise version numbers used by the pack.
+
+.. pull-quote::
+
+   Note
+
+   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 ":doc:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`."

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

@@ -72,3 +72,53 @@ 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 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/*'
+     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.
+
+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>