ci: publish releases automatically on a tag push

.github/workflows/build-macos.yml

@@ -6,9 +6,10 @@ on:
     branches:
       - dev
       - release
+  workflow_call:
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: macos-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
@@ -58,7 +59,7 @@ jobs:
         run: make llvm-source
       - name: Save LLVM source cache
         uses: actions/cache/save@v5
-        if: steps.cache-llvm-source.outputs.cache-hit != 'true'
+        if: steps.cache-llvm-source.outputs.cache-hit != 'true' && github.ref_type != 'tag'
         with:
           key: ${{ steps.cache-llvm-source.outputs.cache-primary-key }}
           path: |
@@ -86,7 +87,7 @@ jobs:
           find llvm-build -name CMakeFiles -prune -exec rm -r '{}' \;
       - name: Save LLVM build cache
         uses: actions/cache/save@v5
-        if: steps.cache-llvm-build.outputs.cache-hit != 'true'
+        if: steps.cache-llvm-build.outputs.cache-hit != 'true' && github.ref_type != 'tag'
         with:
           key: ${{ steps.cache-llvm-build.outputs.cache-primary-key }}
           path: llvm-build

.github/workflows/linux.yml

@@ -6,9 +6,10 @@ on:
     branches:
       - dev
       - release
+  workflow_call:
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: linux-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
@@ -78,7 +79,7 @@ jobs:
         run: make llvm-source
       - name: Save LLVM source cache
         uses: actions/cache/save@v5
-        if: steps.cache-llvm-source.outputs.cache-hit != 'true'
+        if: steps.cache-llvm-source.outputs.cache-hit != 'true' && github.ref_type != 'tag'
         with:
           key: ${{ steps.cache-llvm-source.outputs.cache-primary-key }}
           path: |
@@ -107,7 +108,7 @@ jobs:
           find llvm-build -name CMakeFiles -prune -exec rm -r '{}' \;
       - name: Save LLVM build cache
         uses: actions/cache/save@v5
-        if: steps.cache-llvm-build.outputs.cache-hit != 'true'
+        if: steps.cache-llvm-build.outputs.cache-hit != 'true' && github.ref_type != 'tag'
         with:
           key: ${{ steps.cache-llvm-build.outputs.cache-primary-key }}
           path: llvm-build
@@ -280,7 +281,7 @@ jobs:
         run: make llvm-source
       - name: Save LLVM source cache
         uses: actions/cache/save@v5
-        if: steps.cache-llvm-source.outputs.cache-hit != 'true'
+        if: steps.cache-llvm-source.outputs.cache-hit != 'true' && github.ref_type != 'tag'
         with:
           key: ${{ steps.cache-llvm-source.outputs.cache-primary-key }}
           path: |
@@ -307,7 +308,7 @@ jobs:
           find llvm-build -name CMakeFiles -prune -exec rm -r '{}' \;
       - name: Save LLVM build cache
         uses: actions/cache/save@v5
-        if: steps.cache-llvm-build.outputs.cache-hit != 'true'
+        if: steps.cache-llvm-build.outputs.cache-hit != 'true' && github.ref_type != 'tag'
         with:
           key: ${{ steps.cache-llvm-build.outputs.cache-primary-key }}
           path: llvm-build
@@ -389,7 +390,7 @@ jobs:
         run: make llvm-source
       - name: Save LLVM source cache
         uses: actions/cache/save@v5
-        if: steps.cache-llvm-source.outputs.cache-hit != 'true'
+        if: steps.cache-llvm-source.outputs.cache-hit != 'true' && github.ref_type != 'tag'
         with:
           key: ${{ steps.cache-llvm-source.outputs.cache-primary-key }}
           path: |
@@ -418,7 +419,7 @@ jobs:
           find llvm-build -name CMakeFiles -prune -exec rm -r '{}' \;
       - name: Save LLVM build cache
         uses: actions/cache/save@v5
-        if: steps.cache-llvm-build.outputs.cache-hit != 'true'
+        if: steps.cache-llvm-build.outputs.cache-hit != 'true' && github.ref_type != 'tag'
         with:
           key: ${{ steps.cache-llvm-build.outputs.cache-primary-key }}
           path: llvm-build

.github/workflows/release.yml

@@ -0,0 +1,111 @@
+# Build and publish a GitHub Release when a version tag is pushed.
+#
+# This workflow does not build anything itself: it calls the regular Linux,
+# macOS and Windows workflows, which already produce every file a release
+# needs, and then collects their artifacts into a single draft release.
+#
+# The release is created as a draft on purpose, so the release notes can be
+# reviewed (and the CHANGELOG.md entry pasted in) before publishing.
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  check-version:
+    # The release filenames are derived from goenv/version.go, not from the
+    # tag, so check they agree before spending an hour building everything.
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Check the tag matches goenv/version.go
+        run: |
+          version=$(./.github/workflows/tinygo-extract-version.sh | cut -d= -f2-)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match version $version in goenv/version.go"
+            exit 1
+          fi
+
+  linux:
+    needs: check-version
+    uses: ./.github/workflows/linux.yml
+  macos:
+    needs: check-version
+    uses: ./.github/workflows/build-macos.yml
+  windows:
+    needs: check-version
+    uses: ./.github/workflows/windows.yml
+
+  release:
+    needs: [linux, macos, windows]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Download all release artifacts
+        # Every build job uploads with `archive: false`, which names the
+        # artifact after the file, so this leaves the release files (and
+        # nothing else) directly in dist/. skip-decompress matters for the
+        # Windows release, which is itself a .zip: without it the download
+        # would helpfully unpack the release instead of keeping the file.
+        uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+          skip-decompress: true
+      - name: Check all release files are present
+        # A build that silently stopped uploading must not result in a
+        # half-complete release, so list what is expected explicitly.
+        run: |
+          version=$(./.github/workflows/tinygo-extract-version.sh | cut -d= -f2-)
+          missing=0
+          for file in \
+              "tinygo$version.linux-amd64.tar.gz"  "tinygo_${version}_amd64.deb" \
+              "tinygo$version.linux-arm.tar.gz"    "tinygo_${version}_armhf.deb" \
+              "tinygo$version.linux-arm64.tar.gz"  "tinygo_${version}_arm64.deb" \
+              "tinygo$version.darwin-amd64.tar.gz" \
+              "tinygo$version.darwin-arm64.tar.gz" \
+              "tinygo$version.windows-amd64.zip"; do
+            if [ ! -f "dist/$file" ]; then
+              echo "::error::missing release file $file"
+              missing=1
+            fi
+          done
+          ls -l dist
+          exit $missing
+      - name: Create the draft release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # GitHub computes a SHA-256 digest for every asset it stores, but
+          # only exposes it through the API, so say how to read it. These notes
+          # are prepended to the notes GitHub generates from the commit log.
+          notes=$(cat <<EOF
+          ## Verifying downloads
+
+          GitHub records a SHA-256 digest for every asset below. To print them:
+
+              gh release view $GITHUB_REF_NAME --repo $GITHUB_REPOSITORY --json assets --jq '.assets[] | "\(.digest)  \(.name)"'
+          EOF
+          )
+          prerelease=
+          case "$GITHUB_REF_NAME" in
+            *-alpha*|*-beta*|*-rc*) prerelease=--prerelease ;;
+          esac
+          gh release create "$GITHUB_REF_NAME" \
+            --draft \
+            --verify-tag \
+            $prerelease \
+            --title "$GITHUB_REF_NAME" \
+            --notes "$notes" \
+            --generate-notes \
+            dist/*

.github/workflows/windows.yml

@@ -6,9 +6,10 @@ on:
     branches:
       - dev
       - release
+  workflow_call:
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: windows-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
@@ -52,7 +53,7 @@ jobs:
         run: make llvm-source
       - name: Save cached LLVM source
         uses: actions/cache/save@v5
-        if: steps.cache-llvm-source.outputs.cache-hit != 'true'
+        if: steps.cache-llvm-source.outputs.cache-hit != 'true' && github.ref_type != 'tag'
         with:
           key: ${{ steps.cache-llvm-source.outputs.cache-primary-key }}
           path: |
@@ -80,7 +81,7 @@ jobs:
           find llvm-build -name CMakeFiles -prune -exec rm -r '{}' \;
       - name: Save cached LLVM build
         uses: actions/cache/save@v5
-        if: steps.cache-llvm-build.outputs.cache-hit != 'true'
+        if: steps.cache-llvm-build.outputs.cache-hit != 'true' && github.ref_type != 'tag'
         with:
           key: ${{ steps.cache-llvm-build.outputs.cache-primary-key }}
           path: llvm-build

BUILDING.md

@@ -119,3 +119,31 @@ the following command (for example in ~/lib):
 TinyGo will get extracted to a `tinygo` directory. You can then call it with:
 
     ./tinygo/bin/tinygo
+
+## Publish a release
+
+Releases are built and published by the `Release` workflow
+(`.github/workflows/release.yml`), which runs when a `v*` tag is pushed. There
+is no need to build or upload anything by hand.
+
+ 1. On the `dev` branch, set `const version` in `goenv/version.go` to the new
+    version (without a `v` prefix) and update `CHANGELOG.md`.
+ 2. Merge `dev` into the `release` branch.
+ 3. Tag the release and push the tag:
+
+        git tag v0.42.0
+        git push origin v0.42.0
+
+    The tag must match `goenv/version.go`; the workflow refuses to build
+    otherwise, because the release filenames are derived from that constant.
+ 4. The workflow runs the full Linux, macOS and Windows workflows, so
+    everything that ships is also tested, and then collects their artifacts
+    into a **draft** release: tarballs for linux/darwin, a zip for Windows, and
+    Debian packages for linux.
+ 5. Review the generated release notes, paste in the `CHANGELOG.md` entry, and
+    publish the draft.
+
+GitHub records a SHA-256 digest for every published asset. It is not shown on
+the release page, but it can be read with:
+
+    gh release view v0.42.0 --json assets --jq '.assets[] | "\(.digest)  \(.name)"'