gitlab ci: Rework how mirrors are configured (#39939)

Improve how mirrors are used in gitlab ci, where we have until now thought
of them as only a string.

By configuring ci mirrors ahead of time using the proposed mirror templates,
and by taking advantage of the expressiveness that spack now has for mirrors,
this PR will allow us to easily switch the protocol/url we use for fetching
binary dependencies.

This change also deprecates some gitlab functionality and marks it for
removal in Spack 0.23:

    - arguments to "spack ci generate":
        * --buildcache-destination
        * --copy-to
    - gitlab configuration options:
        * enable-artifacts-buildcache
        * temporary-storage-url-prefix

1 files changed, 10 insertions, 0 deletions

diff --git a/lib/spack/docs/pipelines.rst b/lib/spack/docs/pipelines.rst
index d594879aab..4ebe90fb0b 100644
--- a/lib/spack/docs/pipelines.rst
+++ b/lib/spack/docs/pipelines.rst
@@ -213,6 +213,16 @@ pipeline jobs.
 ``spack ci generate``
 ^^^^^^^^^^^^^^^^^^^^^
 
+Throughout this documentation, references to the "mirror" mean the target
+mirror which is checked for the presence of up-to-date specs, and where
+any scheduled jobs should push built binary packages.  In the past, this
+defaulted to the mirror at index 0 in the mirror configs, and could be
+overridden using the ``--buildcache-destination`` argument. Starting with
+Spack 0.23, ``spack ci generate`` will require you to identify this mirror
+by the name "buildcache-destination".  While you can configure any number
+of mirrors as sources for your pipelines, you will need to identify the
+destination mirror by name.
+
 Concretizes the specs in the active environment, stages them (as described in
 :ref:`staging_algorithm`), and writes the resulting ``.gitlab-ci.yml`` to disk.
 During concretization of the environment, ``spack ci generate`` also writes a