Doc: Note on required changes after merge of reproducible builds (#24347)

* Suggestion of a note for conversion of existing pipelines.

* Wording

* Fix format in .rst note

* Wording

1 files changed, 18 insertions, 1 deletions

diff --git a/lib/spack/docs/pipelines.rst b/lib/spack/docs/pipelines.rst
index 0dcd003e38..884fe44862 100644
--- a/lib/spack/docs/pipelines.rst
+++ b/lib/spack/docs/pipelines.rst
@@ -169,11 +169,28 @@ have disabled it (using ``rebuild-index: False``) because the index would only b
 generated in the artifacts mirror anyway, and consequently would not be available
 during subesequent pipeline runs.
 
+.. note::
+   With the addition of reproducible builds (#22887) a previously working
+   pipeline will require some changes:
+
+   * In the build jobs (``runner-attributes``), the environment location changed.
+     This will typically show as a ``KeyError`` in the failing job. Be sure to
+     point to ``${SPACK_CONCRETE_ENV_DIR}``.
+
+   * When using ``include`` in your environment, be sure to make the included
+     files available in the build jobs. This means adding those files to the
+     artifact directory. Those files will also be missing in the reproducibility
+     artifact.
+
+   * Because the location of the environment changed, including files with
+     relative path may have to be adapted to work both in the project context
+     (generation job) and in the concrete env dir context (build job).
+
 -----------------------------------
 Spack commands supporting pipelines
 -----------------------------------
 
-Spack provides a command ``ci`` command with a few sub-commands supporting spack
+Spack provides a ``ci`` command with a few sub-commands supporting spack
 ci pipelines.  These commands are covered in more detail in this section.
 
 .. _cmd-spack-ci: