Add comments for several design decisions

.github/actions/push-digest-local/action.yaml

@@ -1,8 +1,12 @@
+# Local helper action that pushes an untagged image manifest to a registry via docker 
+# buildx, then records the digest of that manifest and expected tags as github action 
+# artifacts.  Per the docker GHA multi-platform docs, the recommended approach to multi
+# -platform builds is to push an untagged manifest for each arch, then combine them into
+# a single tagged manifest in a separate GHA job.
+
 name: 'Push Container by Digest Action'
 description: 'Pushes an image by digest to a given registry, then outputs its digest and tags as an artifact'
 
-
-
 inputs:
   registry:
     required: true

.github/workflows/build-container.yml

@@ -56,6 +56,8 @@ jobs:
 
 
       - name: Prepare CVMFS
+        # TODO: For all tests, GHA currently only supports amd64 runners. We will need
+        # to re-enable tests on arm64 when ARM runners become available.
         if: ${{ matrix.platform == 'linux/amd64' }}
         run: |
           sudo ./tests/setup_cvmfs.sh
@@ -114,6 +116,10 @@ jobs:
           timestamp: ${{ steps.custom-image-name.outputs.timestamp }}
           output_image: ${{ steps.custom-image-name.outputs.output_image }}
 
+      # TODO: these artifacts will only be tagged if the build succeeds for every arch,
+      # and will remain as cruft in harbor unlesss manually removed in the case that
+      # some arch fails. Handling this scenario is future work: 
+      # https://opensciencegrid.atlassian.net/browse/SOFTWARE-6010
       - id: upload-by-digest-dockerhub
         if: >-
           github.ref == 'refs/heads/master' &&
@@ -190,7 +196,7 @@ jobs:
 
     - name: Check Artifact Count
       env:
-        EXPECTED: 2
+        EXPECTED: 2 # One per build arch
       working-directory: /tmp/${{ matrix.registry.url }}
       run: |
         for dir in tags digests; do