.. ## .. ## Copyright (c) 2022-25, Lawrence Livermore National Security, LLC and .. ## other RADIUSS Project Developers. See the top-level COPYRIGHT file for .. ## details. .. ## .. ## SPDX-License-Identifier: (MIT) .. ## .. _user_how_to-label: ****** How To ****** This section describes how to perform various maintenance tasks once you have the RADIUSS Shared CI framework set up for your project. .. _update-shared-ci: ========================== Updating RADIUSS Shared CI ========================== Component-Based (Recommended) ============================== Update the version tag in all component references. **Before:** .. code-block:: yaml - component: .../base-pipeline@v2025.12.0 **After:** .. code-block:: yaml - component: .../base-pipeline@v2026.02.2 # ← Updated version **Update all components:** .. code-block:: yaml include: - component: .../base-pipeline@v2026.02.2 # ← Update - component: .../utility-draft-pr-filter@v2026.02.2 # ← Update dane-build-and-test: trigger: include: - component: .../dane-pipeline@v2026.02.2 # ← Update .. important:: Use the same version for all components to avoid conflicts. Legacy (Include-Based) ====================== Update the ``ref:`` value. Using a variable lets you update once: **Recommended approach:** .. code-block:: yaml variables: SHARED_CI_REF: v2026.02.2 # ← Update this one value include: - project: 'radiuss/radiuss-shared-ci' ref: ${SHARED_CI_REF} # References the variable file: 'pipelines/dane.yml' .. _leverage-spack: ============== Leverage Spack ============== Initially, the RADIUSS Shared CI infrastructure was designed for RADIUSS projects also using Spack to describe the toolchain and build the dependencies. This "build infrastructure" is defined in `RADIUSS Spack Configs`_ documentation. Spack provides a unified context to express toolchains, machine setup, and build sequence. Spack is increasingly used to install dependency stacks of large simulation codes. Using RADIUSS Spack Configs allows projects to easily share the full context of their builds. .. figure:: images/Full-CI-Infrastructure.png :scale: 30 % :align: center The Shared CI Infrastructure is project agnostic. It is tuned for open-source projects hosted on GitHub and willing to run CI on a GitLab instance. It currently only supports a handful of Livermore Computing machines, but more could be added without disrupting the design. If you were to adopt the full infrastructure, setting up the build infrastructure would be done following two steps: 1. **Use Spack to install dependencies and configure a project build.** 2. **Setup your build system so that it accepts the configuration file generated by Spack.** .. _import-shared-jobs: ================== Import shared jobs ================== RADIUSS projects using RADIUSS Spack Configs share job definitions for common toolchains. Since GitLab doesn't permit including files from submodules, we generate merged job files. This works with both component-based and legacy setups. Setup ===== Add a job in the prerequisites stage to merge shared and local jobs: .. code-block:: yaml generate-job-lists: stage: prerequisites tags: [shell, oslic] variables: RADIUSS_JOBS_PATH: "scripts/radiuss-spack-configs/gitlab/radiuss-jobs" LOCAL_JOBS_PATH: ".gitlab/jobs" script: - cat ${RADIUSS_JOBS_PATH}/dane.yml ${LOCAL_JOBS_PATH}/dane.yml > dane-jobs.yml - cat ${RADIUSS_JOBS_PATH}/corona.yml ${LOCAL_JOBS_PATH}/corona.yml > corona-jobs.yml - cat ${RADIUSS_JOBS_PATH}/tioga.yml ${LOCAL_JOBS_PATH}/tioga.yml > tioga-jobs.yml artifacts: paths: - dane-jobs.yml - corona-jobs.yml - tioga-jobs.yml Usage with Components ===================== Add dependency and use generated artifact: .. code-block:: yaml dane-build-and-test: needs: [dane-up-check, generate-job-lists] # Add dependency extends: [.dane, .build-and-test] trigger: include: - component: .../dane-pipeline@v2026.02.2 - artifact: 'dane-jobs.yml' # Use generated file job: 'generate-job-lists' Usage with Legacy ================= Similar pattern for legacy includes: .. code-block:: yaml dane-build-and-test: needs: [dane-up-check, generate-job-lists] trigger: include: - local: '.gitlab/custom-jobs-and-variables.yml' - project: 'radiuss/radiuss-shared-ci' ref: '${SHARED_CI_REF}' file: 'pipelines/dane.yml' - artifact: 'dane-jobs.yml' job: 'generate-job-lists' .. note:: Local jobs should be defined after shared ones to allow overriding. .. _complex-workflows: ============================== Implement Complex CI Workflows ============================== In the CI setup description, the resulting workflow gathers all the jobs withing one stage, with jobs calling only the ``JOB_CMD`` one-line command. Restricting the job command to a one-liner is required because we append it to an allocation call. In our opinion, it is not restrictive because it is a good practice to define your scripts outside the CI YAML files. However, it may appear restrictive to only allow one-stage pipelines. In facts, the RADIUSS Shared CI defines 3 stages for you to use. They are named ``jobs-stage-<1,2,3>``. They stand between the ``allocate-resources`` and the ``release-resources`` stages, which means that jobs will run within the shared allocation as long as they inherit from the shared job template (``extends: .job_on_``). In your local jobs definition, you may pick the stage with the key ``stages: jobs-stage-<1,2,3>``. This will override the default value set in the job template (``jobs-stage-1``). It is also possible to go further in the customization and override the list of stages to add more. We only warn you that a good understanding of the Shared CI implementation is required before overriding it. .. warning:: GitLab YAML syntax allows you to override any section previously defined. This opens to door to deep customization of the Shared CI implementation. However it requires a good understanding of how the Shared CI works. In general, we advise you to start by submitting a feature requests on GitHub: we are open to suggestions and can help with your customization needs. .. _RADIUSS Spack Configs: https://radiuss-spack-configs.readthedocs.io/en/latest/index.html .. _radiuss-spack-configs: https://github.com/LLNL/radiuss-spack-configs .. _Uberenv: https://github.com/LLNL/uberenv .. _Spack: https://github.com/spack/spack ======== See Also ======== - :doc:`setup-with-components` - Initial setup guide - :doc:`quick-reference` - Quick reference for variables and components - :doc:`troubleshooting` - Common issues - :doc:`../reference/components/index` - Component reference