Update README with signature verification & release structure

Also clean up build.yml

Signed-off-by: Gary Oberbrunner <[email protected]>

Author: garyo

.github/workflows/build.yml

@@ -204,6 +204,9 @@ jobs:
 
       # Q: should we use uv everywhere?
       # Unfortunately astral-sh/setup-uv action doesn't work on CentOS 7, its GLIBC is too old.
+      # BUT this CI build doesn't work on CentOS 7 anyway, due to recent github changes.
+      # Keep this uv code in case we'd like to install python and conan with uv, but for now
+      # it is not used.
 
       - name: Set up uv manually
         if: matrix.release_prefix == 'linux-vfx2021'
@@ -337,6 +340,11 @@ jobs:
             # should build Support/Plugins too, but those need work            
           fi
 
+      ############################################################
+      # Installation: produce release artifacts
+      ############################################################
+
+
       - name: Copy includes and libs into release folder for installation
         # Dir structure:
         #  Install/OpenFX
@@ -387,17 +395,12 @@ jobs:
           upload-signing-artifacts: false
           release-signing-artifacts: false
 
-      - run: |
-          ls -l
-
       - name: Upload header/libs tarball and signatures
         uses: actions/upload-artifact@v4
         with:
           name: "openfx-${{ env.RELEASE_NAME }}"
           path: |
             openfx-${{ env.RELEASE_NAME }}.tar.gz
-            openfx-${{ env.RELEASE_NAME }}.tar.gz.sig
-            openfx-${{ env.RELEASE_NAME }}.tar.gz.crt
             openfx-${{ env.RELEASE_NAME }}.tar.gz.sigstore.json
 
       # Now the same, for the plugins
@@ -420,12 +423,4 @@ jobs:
           name: "openfx-plugins-${{ env.RELEASE_NAME }}"
           path: |
             openfx-plugins-${{ env.RELEASE_NAME }}.tar.gz
-            openfx-plugins-${{ env.RELEASE_NAME }}.tar.gz.sig
-            openfx-plugins-${{ env.RELEASE_NAME }}.tar.gz.crt
             openfx-plugins-${{ env.RELEASE_NAME }}.tar.gz.sigstore.json
-
-      # - name: Upload release archive
-      #   # if: github.event_name == 'release'
-      #   env:
-      #     GH_TOKEN: ${{ github.token }}
-      #   run: gh release upload ${TAG} ${OPENFX_TARBALL} ${OPENFX_TARBALL}.sigstore.json

.github/workflows/release-sign.yml

@@ -61,3 +61,36 @@ See instructions in [Documentation/README.md](Documentation/README.md).
    - use `git tag -a -s` to sign with the release gpg key
 * Push that tag to github, then create the release on github from that tag.
 * Publish the release on github; that will run the release publish workflow, creating and uploading the sigstore-signed artifacts.
+
+# Releases
+
+Release bundles are named like `openfx-<OS>-release-<REL>.zip` and `openfx-plugins-<OS>-release-<REL>.zip`.
+The `openfx-*` bundles contain all the header files as well as the support libs. They look like this:
+
+```
+OpenFX
+├── include
+│  └── openfx
+│     ├── ofxCore.h...
+│     ├── HostSupport/*.h
+│     └── Support/*.h
+└── lib
+   ├── lib*
+```
+
+so you can add compiler/linker options `-I.../OpenFX/include` `-LOpenFX/lib` and then in source files `#include "openfx/ofxCore.h"` etc.
+
+The `openfx-plugins-*` bundles contain all the sample plugins for the OS. Copy these into your [plugin install dir](https://openfx.readthedocs.io/en/latest/Reference/ofxPackaging.html#installation-directory-hierarchy) and they should show up in your host application.
+
+## Verifying Release Signatures
+
+We use [`sigstore`](https://github.com/marketplace/actions/gh-action-sigstore-python) to sign our github releases. 
+Release signatures are created using short-lived certificates, and audit trails are stored online using `rekor.sigstore.com`. 
+To verify a release artifact (zip file), unpack the zip into a `.tgz` and its associated `.tgz.sigstore.json`, and then use [`cosign`](https://docs.sigstore.dev/cosign/system_config/installation/) to verify the signature like this:
+```
+cosign verify-blob \
+  openfx-mac-release-x.y.tar.gz \
+  --bundle openfx-mac-release-x.y.tar.gz.sigstore.json \
+  --new-bundle-format \
+  --certificate-identity-regexp='https://github.com/AcademySoftwareFoundation/openfx/.*' \ --certificate-oidc-issuer='https://token.actions.githubusercontent.com'
+```