Spack V1 Migration Feature: Reserved Spack Definitions (#332)

* Rename action from get-spack-root-spec to get-spack-manifest, return only deployment-[name|version]

* cd.yml: Use get-spack-manifest, rework job names

* ci-comment.yml: Use get-spack-manifest, simplify update and commit of the bump

* deploy-1-setup.yml: Use get-spack-manifest, remove check on root spec usage

* deploy-2-start.yml: Remove unused manifest information

* fix: Add manifest path to action

* Update modules.py, prerelease.py to use reserved defs _name and _version

* Update tests

* Make reserved definitions flow-style for module injection too

* Remove references to RootSpecs, use ReservedDefinitions.get("name"), remove --keep-root-spec-intact flag

* Update pkg_repo_url logic to use spack.repo.PATH.get_pkg_class()

* getter.py fixes from code review
Update reserved defs getter return value, remove case statement, revert autoformatter

* Update test input manifest formatting

* Add back manifest info step

* Update pre/release injections to handle multiple specs, simplify custom release projection logic

* Change release injection --packages from space-sep to comma-sep, as convention

* Update tests

* Explicitly disallow multi-spec Releases

* get-spack-manifest: call the getter.py script

* Import yaml representers from own class

* Small fixes

Author: CodeGat

.github/actions/get-spack-manifest/README.md

@@ -0,0 +1,38 @@
+# Get Spack Manifest Information
+
+Action that returns information about a Spack manifest file.
+
+## Inputs
+
+> [!NOTE]
+> Action assumes that an appropriate repository is checked out prior to invocation
+
+| Name | Type | Description | Required | Default | Example |
+| ---- | ---- | ----------- | -------- | ------- | ------- |
+| `spack-manifest-path` | `string` | The path to the spack manifest file | `false` | `"./spack.yaml"` | `"./some/other.spack.yaml"` |
+
+## Outputs
+
+| Name | Type | Description | Example |
+| ---- | ---- | ----------- | ------- |
+| `deployment-name` | `string` | The name of the deployment as specified in the reserved definition `_name` | `access-om2` |
+| `deployment-version` | `string` | The version of the deployment as specified in the reserved definition `_version` | `2025.11.000` |
+
+## Example
+
+```yaml
+# ...
+jobs:
+  manifest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - id: spec
+        uses: access-nri/build-cd/.github/actions/get-spack-manifest@vX  # for some version `vX`
+        with:
+          spack-manifest-path: ./spack.yaml
+
+      - run: |
+          echo "Deploying ${{ steps.spec.outputs.deployment-name }} at ${{ steps.spec.outputs.deployment-version }}"
+```

.github/actions/get-spack-manifest/action.yml

@@ -0,0 +1,52 @@
+name: Get Spack Manifest Information
+description: Action that returns information about a Spack manifest file
+author: Tommy Gatti
+inputs:
+  spack-manifest-path:
+    required: false
+    default: ./spack.yaml
+    description: The path to the spack manifest file
+outputs:
+  deployment-name:
+    description: |
+      The name of the deployment as specified in the reserved definition _name, in the spack manifest file.
+    value: ${{ steps.defs.outputs.name }}
+  deployment-version:
+    description: |
+      The version of the deployment as specified in the reserved definition _version, in the spack manifest file.
+    value: ${{ steps.defs.outputs.version }}
+runs:
+  using: composite
+  steps:
+    - name: Clone build-cd script location
+      uses: actions/checkout@v4
+      with:
+        repository: access-nri/build-cd
+        path: ${{ github.workspace }}/getter-script
+
+    - name: Get Current Directory
+      id: script
+      # We need to store the current working directory so we can re-construct the inputs.spack-manifest-path, as we run
+      # the script from the build-cd directory
+      shell: bash
+      run: |
+        pwd=$(pwd)
+        echo "Action PWD: $pwd"
+        echo "pwd=$pwd" >> $GITHUB_OUTPUT
+
+    - name: Get reserved definitions
+      id: defs
+      env:
+        PYTHONPATH: ${{ github.workspace }}/getter-script
+      shell: python
+      run: |
+        from scripts.spack_manifest.getter import ReservedDefinitions
+        import os
+
+        defs = ReservedDefinitions.from_file("${{ steps.script.outputs.pwd }}/${{ inputs.spack-manifest-path }}")
+        name = defs.get("name")
+        version = defs.get("version")
+
+        with open(os.environ['GITHUB_OUTPUT'], 'a') as o:
+          o.write(f"name={name}\n")
+          o.write(f"version={version}\n")

.github/actions/get-spack-root-spec/README.md

@@ -114,19 +114,19 @@ jobs:
           target: ${{ matrix.target }}
           error-level: error
 
-  get-root-spec-ref:
-    name: Get root spec ref
+  get-deployment-version:
+    name: Get Deployment Version
     runs-on: ubuntu-latest
     needs:
       - verify-settings
     outputs:
-      root-spec-ref: ${{ steps.tag.outputs.root-spec-ref }}
+      version: ${{ steps.manifest.outputs.deployment-version }}
     steps:
       - uses: actions/checkout@v4
 
-      - name: Get root spec ref
-        id: tag
-        uses: access-nri/build-cd/.github/actions/get-spack-root-spec@v8
+      - name: Get Deployment Version
+        id: manifest
+        uses: access-nri/build-cd/.github/actions/get-spack-manifest@v8
         with:
           spack-manifest-path: ${{ inputs.spack-manifest-path }}
 
@@ -135,7 +135,7 @@ jobs:
     if: inputs.tag-deployment
     runs-on: ubuntu-latest
     needs:
-      - get-root-spec-ref
+      - get-deployment-version
     permissions:
       contents: write
     steps:
@@ -155,27 +155,22 @@ jobs:
 
       - name: Push Tag
         env:
-          TAG: ${{ needs.get-root-spec-ref.outputs.root-spec-ref }}
+          TAG: ${{ needs.get-deployment-version.outputs.version }}
         run: |
-          if [[ "${{ env.TAG }}" == "latest" ]]; then
-            echo "::error::The version 'latest' is reserved for a spack package that moves often and cannot be used as a release tag. Reset the 'main' or 'backport' branch, reopen the merged PR, and update the version."
-            exit 1
-          fi
-
           git tag ${{ env.TAG }} -m "Deployment of ${{ inputs.model }} ${{ env.TAG }} via build-cd 'cd.yml' workflow"
           git push --tags
 
   deploy-release:
     name: Deploy Release
     needs:
       - defaults
-      - get-root-spec-ref
+      - get-deployment-version
       - push-tag
     # Pushing tags is optional if we are doing a non-model deployment
     if: >-
       always() &&
       needs.defaults.result == 'success' &&
-      needs.get-root-spec-ref.result == 'success' &&
+      needs.get-deployment-version.result == 'success' &&
       (needs.push-tag.result == 'success' || needs.push-tag.result == 'skipped')
     strategy:
       matrix:
@@ -185,7 +180,7 @@ jobs:
       deployment-target: ${{ matrix.target }}
       deployment-ref: ${{ github.ref_name }}
       deployment-type: Release
-      deployment-version: ${{ needs.get-root-spec-ref.outputs.root-spec-ref }}
+      deployment-version: ${{ needs.get-deployment-version.outputs.version }}
       spack-manifest-path: ${{ inputs.spack-manifest-path }}
       expected-root-spec-name: ${{ needs.defaults.outputs.root-sbd }}
       spack-manifest-schema-path: ${{ inputs.spack-manifest-schema-path }}
@@ -204,7 +199,7 @@ jobs:
     if: inputs.tag-deployment
     needs:
       - defaults
-      - get-root-spec-ref
+      - get-deployment-version
       - push-tag
       - deploy-release
     runs-on: ubuntu-latest
@@ -245,7 +240,7 @@ jobs:
         id: release-body
         env:
           J2_MODEL: ${{ inputs.model }}
-          J2_VERSION: ${{ needs.get-root-spec-ref.outputs.root-spec-ref }}
+          J2_VERSION: ${{ needs.get-deployment-version.outputs.version }}
           J2_ROOT_SBD: ${{ needs.defaults.outputs.root-sbd }}
         run: |
           python -m scripts.jinja_template.render_deployment_info \
@@ -256,8 +251,8 @@ jobs:
       - name: Create Release
         uses: softprops/action-gh-release@69320dbe05506a9a39fc8ae11030b214ec2d1f87  # v2.0.5
         with:
-          tag_name: ${{ needs.get-root-spec-ref.outputs.root-spec-ref }}
-          name: ${{ inputs.model}} ${{ needs.get-root-spec-ref.outputs.root-spec-ref }}
+          tag_name: ${{ needs.get-deployment-version.outputs.version }}
+          name: ${{ inputs.model}} ${{ needs.get-deployment-version.outputs.version }}
           body_path: ${{ env.TEMPLATED_RELEASE_BODY_PATH }}
           generate_release_notes: true
           fail_on_unmatched_files: true

.github/actions/get-spack-root-spec/action.yml

@@ -73,7 +73,7 @@ jobs:
 
       - name: Original version
         id: original
-        uses: access-nri/build-cd/.github/actions/get-spack-root-spec@v8
+        uses: access-nri/build-cd/.github/actions/get-spack-manifest@v8
 
       - name: Setup
         id: setup
@@ -99,11 +99,11 @@ jobs:
               echo "version=${tag_date}" >> $GITHUB_OUTPUT
               echo "bump=major" >> $GITHUB_OUTPUT
             else
-              echo "version=${{ steps.original.outputs.root-spec-ref }}" >> $GITHUB_OUTPUT
+              echo "version=${{ steps.original.outputs.deployment-version }}" >> $GITHUB_OUTPUT
               echo "bump=current" >> $GITHUB_OUTPUT
             fi
           elif [[ "${{ contains(github.event.comment.body, 'minor')}}" == "true" ]]; then
-            echo "version=${{ steps.original.outputs.root-spec-ref }}" >> $GITHUB_OUTPUT
+            echo "version=${{ steps.original.outputs.deployment-version }}" >> $GITHUB_OUTPUT
             echo "bump=minor" >> $GITHUB_OUTPUT
           else
             echo "::warning::Usage: `!bump [major|minor]`, got `${{ github.event.comment.body }}`"
@@ -131,22 +131,17 @@ jobs:
           git_tag_gpgsign: true
 
       - name: Update, Commit and Push the Bump
-        env:
-          # If the root spec contained an '=VERSION' segment, we want to add that back to the updated root spec, too
-          OPTIONAL_VERSION: ${{ steps.original.outputs.root-spec-version != '' && format('={0}', steps.original.outputs.root-spec-version) || '' }}
         run: |
-          updated_spec="${{ needs.defaults.outputs.root-sbd }}@git.${{ steps.bump.outputs.after }}${{ env.OPTIONAL_VERSION }}"
-          yq -i "${{ steps.original.outputs.yq-root-spec }} = \"$updated_spec\"" spack.yaml
-          yq -i '${{ env.SPACK_YAML_MODEL_PROJECTION_YQ }} = "{name}/${{ steps.bump.outputs.after }}"' spack.yaml
+          yq -i '.spack.definitions[]._version[0] = "${{ steps.bump.outputs.after }}"' spack.yaml
           git add spack.yaml
-          git commit -m "spack.yaml: Updated ${{ needs.defaults.outputs.root-sbd }} package version from ${{ steps.original.outputs.root-spec-ref }} to ${{ steps.bump.outputs.after }}"
+          git commit -m "spack.yaml: Updated deployment version from ${{ steps.original.outputs.deployment-version }} to ${{ steps.bump.outputs.after }}"
           git push
 
       - name: Success Notifier
         uses: access-nri/actions/.github/actions/pr-comment@main
         with:
           comment: |
-            :white_check_mark: Version bumped from `${{ steps.original.outputs.root-spec-ref }}` to `${{ steps.bump.outputs.after }}` :white_check_mark:
+            :white_check_mark: Version bumped from `${{ steps.original.outputs.deployment-version }}` to `${{ steps.bump.outputs.after }}` :white_check_mark:
 
       - name: Failure Notifier
         if: failure()