feat: release artifact attestations (#383)

Author: scop

.github/workflows/publish.yml

@@ -7,6 +7,10 @@ jobs:
   publish_release:
     name: Release
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+      attestations: write
     steps:
       - name: Checkout head
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
@@ -48,6 +52,10 @@ jobs:
           HOMEBREW_TAP_GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
       - name: Clear Docker login session
         run: rm -f ${HOME}/.docker/config.json
+      - name: Generate artifact attestations
+        uses: actions/attest-build-provenance@f9eaf234fc1c2e333c1eca18177db0f44fa6ba52 # v2.2.1
+        with:
+          subject-checksums: dist/checksums.txt
       - name: Generate AUR PKGBUILD
         run: ./scripts/generate_aur_pkgbuild.sh ${{ steps.git.outputs.tag_version }}
       - name: Publish AUR package

RELEASING.md

@@ -8,6 +8,6 @@
       - sets the version based on the tag
       - creates a draft release to GitHub
       - populates the release notes from `CHANGELOG.md` with `make release-notes`
-      - builds and uploads binaries & SHA sum for given release
+      - builds, uploads, and generates provenance for given release
 5. Verify that [release notes](https://github.com/UpCloudLtd/upcloud-cli/releases) are in line with `CHANGELOG.MD`
 6. Publish the drafted release

docs/index.md

@@ -16,13 +16,15 @@ using a package manager, Docker image, or from sources with `go install`:
 
     ```sh
     curl -Lo upcloud-cli_{{ latest_release }}_amd64.deb https://github.com/UpCloudLtd/upcloud-cli/releases/download/v{{ latest_release }}/upcloud-cli_{{ latest_release }}_amd64.deb
+    # Preferably verify the asset before proceeding with install, see "Verify assets" below
     sudo apt install ./upcloud-cli_{{ latest_release }}_amd64.deb
     ```
 
     On RHEL based distributions, use the `.rpm` package.
 
     ```sh
     curl -Lo upcloud-cli-{{ latest_release }}-1.x86_64.rpm https://github.com/UpCloudLtd/upcloud-cli/releases/download/v{{ latest_release }}/upcloud-cli-{{ latest_release }}-1.x86_64.rpm
+    # Preferably verify the asset before proceeding with install, see "Verify assets" below
     sudo dnf install ./upcloud-cli-{{ latest_release }}-1.x86_64.rpm
     ```
 
@@ -41,6 +43,7 @@ using a package manager, Docker image, or from sources with `go install`:
 
     ```pwsh
     Invoke-WebRequest -Uri "https://github.com/UpCloudLtd/upcloud-cli/releases/download/v{{ latest_release }}/upcloud-cli_{{ latest_release }}_windows_x86_64.zip" -OutFile "upcloud-cli_{{ latest_release }}_windows_x86_64.zip"
+    # Preferably verify the asset before proceeding with install, see "Verify assets" below
     Expand-Archive -Path "upcloud-cli_{{ latest_release }}_windows_x86_64.zip"
 
     # Print current location
@@ -106,6 +109,35 @@ After installing `upctl`, you can run `upctl version` command to verify that the
 upctl version
 ```
 
+### Verify assets
+
+[GitHub artifact attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations)
+and plain old checksum files are available for verifying release assets.
+
+=== "Attestations"
+
+    [Release asset artifact attestations](https://github.com/UpCloudLtd/upcloud-cli/attestations)
+    can be verified for example with the [GitHub CLI](https://github.com/cli/cli),
+    using the Linux x86_64 asset as an example:
+
+    ```sh
+    gh attestation verify \
+        /path/to/locally/downloaded/upcloud-cli_{{ latest_release }}_linux_x86_64.tar.gz \
+        --repo UpCloudLtd/upcloud-cli
+    ```
+
+    Attestations are available starting from version 3.16.0.
+
+=== "Digests"
+
+    Release assets' SHA-256 digests are available in releases,
+    in asset named `checksums.txt`. They can be checked for example with:
+
+    ```sh
+    # make sure at least one downloaded asset and checksums.txt are in the current directory
+    sha256sum -c --ignore-missing checksums.txt
+    ```
+
 ### Configure shell completions
 
 `upctl` provides shell completions for multiple shells. Run `upctl completion --help` to list the supported shells.