ci: release tag workflow (#3036)

This adds a new workflow for building and releasing _tagged versions_ of Ghostty. The workflow is triggered automatically by new tags in the format of `vX.Y.Z` but can also be manually triggered by running the workflow from the GitHub Actions UI. Release artifacts are uploaded to a completely separate R2 bucket with its own access policy, retention, API keys, and so on. There is currently no way to switch between "channels" in the macOS app. I will follow up with a separate commit to add this feature.
2025-07-15 16:26:08 +03:00 · 2024-12-20 13:36:18 -08:00
parent ef56fe8796 0abd4ea8a2
commit a34c8ba7ce
5 changed files with 415 additions and 7 deletions
--- a/.github/workflows/release-tag.yml
+++ b/.github/workflows/release-tag.yml
@ -4,6 +4,9 @@ on:
      version:
        description: "Version to deploy (format: vX.Y.Z)"
        required: true
+      upload:
+        description: "Upload final artifacts to R2"
+        default: false
  push:
    tags:
      - "v[0-9]+.[0-9]+.[0-9]+"
@ -21,6 +24,9 @@ jobs:
    runs-on: namespace-profile-ghostty-sm
    outputs:
      version: ${{ steps.extract_version.outputs.version }}
+      build: ${{ steps.extract_build_info.outputs.build }}
+      commit: ${{ steps.extract_build_info.outputs.commit }}
+      commit_long: ${{ steps.extract_build_info.outputs.commit_long }}
    steps:
      - name: Validate Version Input
        if: github.event_name == 'workflow_dispatch'
@ -48,6 +54,23 @@ jobs:
            exit 1
          fi

+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          # Important so that build number generation works
+          fetch-depth: 0
+
+      - name: Extract build info
+        id: extract_build_info
+        run: |
+          GHOSTTY_BUILD=$(git rev-list --count HEAD)
+          GHOSTTY_COMMIT=$(git rev-parse --short HEAD)
+          GHOSTTY_COMMIT_LONG=$(git rev-parse HEAD)
+          echo "build=$GHOSTTY_BUILD" >> $GITHUB_OUTPUT
+          echo "commit=$GHOSTTY_COMMIT" >> $GITHUB_OUTPUT
+          echo "commit_long=$GHOSTTY_COMMIT_LONG" >> $GITHUB_OUTPUT
+          cat $GITHUB_OUTPUT
+
  source-tarball:
    runs-on: namespace-profile-ghostty-md
    needs: [setup]
@ -73,9 +96,275 @@ jobs:
          nix develop -c minisign -S -m ghostty-source.tar.gz -s minisign.key < minisign.password

      - name: Upload artifact
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
        with:
          name: source-tarball
          path: |-
            ghostty-source.tar.gz
            ghostty-source.tar.gz.minisig
+
+  build-macos:
+    needs: [setup]
+    runs-on: namespace-profile-ghostty-macos
+    timeout-minutes: 90
+    env:
+      GHOSTTY_VERSION: ${{ needs.setup.outputs.version }}
+      GHOSTTY_BUILD: ${{ needs.setup.outputs.build }}
+      GHOSTTY_COMMIT: ${{ needs.setup.outputs.commit }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - uses: cachix/install-nix-action@v30
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+      - uses: cachix/cachix-action@v15
+        with:
+          name: ghostty
+          authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
+
+      - name: XCode Select
+        run: sudo xcode-select -s /Applications/Xcode_16.0.app
+
+      - name: Setup Sparkle
+        env:
+          SPARKLE_VERSION: 2.6.3
+        run: |
+          mkdir -p .action/sparkle
+          cd .action/sparkle
+          curl -L https://github.com/sparkle-project/Sparkle/releases/download/${SPARKLE_VERSION}/Sparkle-for-Swift-Package-Manager.zip > sparkle.zip
+          unzip sparkle.zip
+          echo "$(pwd)/bin" >> $GITHUB_PATH
+
+      # GhosttyKit is the framework that is built from Zig for our native
+      # Mac app to access. Build this in release mode.
+      - name: Build GhosttyKit
+        run: nix develop -c zig build -Doptimize=ReleaseFast
+
+      # The native app is built with native XCode tooling. This also does
+      # codesigning. IMPORTANT: this must NOT run in a Nix environment.
+      # Nix breaks xcodebuild so this has to be run outside.
+      - name: Build Ghostty.app
+        run: |
+          cd macos
+          xcodebuild -target Ghostty -configuration Release
+
+      # Add all our metadata to Info.plist so we can reference it later.
+      - name: Update Info.plist
+        env:
+          SPARKLE_KEY_PUB: ${{ secrets.PROD_MACOS_SPARKLE_KEY_PUB }}
+        run: |
+          # Version Info
+          /usr/libexec/PlistBuddy -c "Set :GhosttyCommit $GHOSTTY_COMMIT" "macos/build/Release/Ghostty.app/Contents/Info.plist"
+          /usr/libexec/PlistBuddy -c "Set :CFBundleVersion $GHOSTTY_BUILD" "macos/build/Release/Ghostty.app/Contents/Info.plist"
+          /usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $GHOSTTY_VERSION" "macos/build/Release/Ghostty.app/Contents/Info.plist"
+
+          # Updater
+          /usr/libexec/PlistBuddy -c "Set :SUPublicEDKey $SPARKLE_KEY_PUB" "macos/build/Release/Ghostty.app/Contents/Info.plist"
+
+      - name: Codesign app bundle
+        env:
+          MACOS_CERTIFICATE: ${{ secrets.PROD_MACOS_CERTIFICATE }}
+          MACOS_CERTIFICATE_PWD: ${{ secrets.PROD_MACOS_CERTIFICATE_PWD }}
+          MACOS_CERTIFICATE_NAME: ${{ secrets.PROD_MACOS_CERTIFICATE_NAME }}
+          MACOS_CI_KEYCHAIN_PWD: ${{ secrets.PROD_MACOS_CI_KEYCHAIN_PWD }}
+        run: |
+          # Turn our base64-encoded certificate back to a regular .p12 file
+          echo $MACOS_CERTIFICATE | base64 --decode > certificate.p12
+
+          # We need to create a new keychain, otherwise using the certificate will prompt
+          # with a UI dialog asking for the certificate password, which we can't
+          # use in a headless CI environment
+          security create-keychain -p "$MACOS_CI_KEYCHAIN_PWD" build.keychain
+          security default-keychain -s build.keychain
+          security unlock-keychain -p "$MACOS_CI_KEYCHAIN_PWD" build.keychain
+          security import certificate.p12 -k build.keychain -P "$MACOS_CERTIFICATE_PWD" -T /usr/bin/codesign
+          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$MACOS_CI_KEYCHAIN_PWD" build.keychain
+
+          # Codesign Sparkle. Some notes here:
+          #   - The XPC services aren't used since we don't sandbox Ghostty,
+          #     but since they're part of the build, they still need to be
+          #     codesigned.
+          #   - The binaries in the "Versions" folders need to NOT be symlinks.
+          /usr/bin/codesign --verbose -f -s "$MACOS_CERTIFICATE_NAME" -o runtime "macos/build/Release/Ghostty.app/Contents/Frameworks/Sparkle.framework/Versions/B/XPCServices/Downloader.xpc"
+          /usr/bin/codesign --verbose -f -s "$MACOS_CERTIFICATE_NAME" -o runtime "macos/build/Release/Ghostty.app/Contents/Frameworks/Sparkle.framework/Versions/B/XPCServices/Installer.xpc"
+          /usr/bin/codesign --verbose -f -s "$MACOS_CERTIFICATE_NAME" -o runtime "macos/build/Release/Ghostty.app/Contents/Frameworks/Sparkle.framework/Versions/B/Autoupdate"
+          /usr/bin/codesign --verbose -f -s "$MACOS_CERTIFICATE_NAME" -o runtime "macos/build/Release/Ghostty.app/Contents/Frameworks/Sparkle.framework/Versions/B/Updater.app"
+          /usr/bin/codesign --verbose -f -s "$MACOS_CERTIFICATE_NAME" -o runtime "macos/build/Release/Ghostty.app/Contents/Frameworks/Sparkle.framework"
+
+          # Codesign the app bundle
+          /usr/bin/codesign --verbose -f -s "$MACOS_CERTIFICATE_NAME" -o runtime --entitlements "macos/Ghostty.entitlements" macos/build/Release/Ghostty.app
+
+      - name: "Notarize app bundle"
+        env:
+          PROD_MACOS_NOTARIZATION_APPLE_ID: ${{ secrets.PROD_MACOS_NOTARIZATION_APPLE_ID }}
+          PROD_MACOS_NOTARIZATION_TEAM_ID: ${{ secrets.PROD_MACOS_NOTARIZATION_TEAM_ID }}
+          PROD_MACOS_NOTARIZATION_PWD: ${{ secrets.PROD_MACOS_NOTARIZATION_PWD }}
+        run: |
+          # Store the notarization credentials so that we can prevent a UI password dialog
+          # from blocking the CI
+          echo "Create keychain profile"
+          xcrun notarytool store-credentials "notarytool-profile" --apple-id "$PROD_MACOS_NOTARIZATION_APPLE_ID" --team-id "$PROD_MACOS_NOTARIZATION_TEAM_ID" --password "$PROD_MACOS_NOTARIZATION_PWD"
+
+          # We can't notarize an app bundle directly, but we need to compress it as an archive.
+          # Therefore, we create a zip file containing our app bundle, so that we can send it to the
+          # notarization service
+          echo "Creating temp notarization archive"
+          ditto -c -k --keepParent "macos/build/Release/Ghostty.app" "notarization.zip"
+
+          # Here we send the notarization request to the Apple's Notarization service, waiting for the result.
+          # This typically takes a few seconds inside a CI environment, but it might take more depending on the App
+          # characteristics. Visit the Notarization docs for more information and strategies on how to optimize it if
+          # you're curious
+          echo "Notarize app"
+          xcrun notarytool submit "notarization.zip" --keychain-profile "notarytool-profile" --wait
+
+          # Finally, we need to "attach the staple" to our executable, which will allow our app to be
+          # validated by macOS even when an internet connection is not available.
+          echo "Attach staple"
+          xcrun stapler staple "macos/build/Release/Ghostty.app"
+
+      # Zip up the app and symbols
+      - name: Zip App
+        run: |
+          cd macos/build/Release
+          zip -9 -r --symlinks ../../../ghostty-macos-universal.zip Ghostty.app
+          zip -9 -r --symlinks ../../../ghostty-macos-universal-dsym.zip Ghostty.app.dSYM/
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos
+          path: |-
+            ghostty-macos-universal.zip
+            ghostty-macos-universal-dsym.zip
+
+  sentry-dsym:
+    runs-on: namespace-profile-ghostty-sm
+    needs: [build-macos]
+    steps:
+      - name: Install sentry-cli
+        run: |
+          curl -sL https://sentry.io/get-cli/ | bash
+
+      - name: Download macOS Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: macos
+
+      - name: Upload dSYM to Sentry
+        env:
+          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+        run: |
+          sentry-cli dif upload --project ghostty --wait ghostty-macos-universal-dsym.zip
+
+  appcast:
+    needs: [setup, build-macos]
+    runs-on: namespace-profile-ghostty-macos
+    env:
+      GHOSTTY_VERSION: ${{ needs.setup.outputs.version }}
+      GHOSTTY_BUILD: ${{ needs.setup.outputs.build }}
+      GHOSTTY_COMMIT: ${{ needs.setup.outputs.commit }}
+      GHOSTTY_COMMIT_LONG: ${{ needs.setup.outputs.commit_long }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Download macOS Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: macos
+
+      - name: Setup Sparkle
+        env:
+          SPARKLE_VERSION: 2.6.3
+        run: |
+          mkdir -p .action/sparkle
+          cd .action/sparkle
+          curl -L https://github.com/sparkle-project/Sparkle/releases/download/${SPARKLE_VERSION}/Sparkle-for-Swift-Package-Manager.zip > sparkle.zip
+          unzip sparkle.zip
+          echo "$(pwd)/bin" >> $GITHUB_PATH
+
+      - name: Generate Appcast
+        env:
+          SPARKLE_KEY: ${{ secrets.PROD_MACOS_SPARKLE_KEY }}
+        run: |
+          echo "GHOSTTY_VERSION=$GHOSTTY_VERSION"
+          echo "GHOSTTY_BUILD=$GHOSTTY_BUILD"
+          echo "GHOSTTY_COMMIT=$GHOSTTY_COMMIT"
+          echo "GHOSTTY_COMMIT_LONG=$GHOSTTY_COMMIT_LONG"
+
+          echo $SPARKLE_KEY > signing.key
+          sign_update -f signing.key ghostty-macos-universal.zip > sign_update.txt
+          curl -L https://release.files.ghostty.org/appcast.xml > appcast.xml
+          python3 ./dist/macos/update_appcast_tag.py
+          test -f appcast_new.xml
+          mv appcast_new.xml appcast.xml
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sparkle
+          path: |-
+            appcast.xml
+
+  upload:
+    if: |-
+      (github.event_name == 'workflow_dispatch' &&
+        github.event.inputs.upload == 'true') ||
+      github.event_name == 'push'
+    needs: [setup, source-tarball, build-macos, appcast]
+    runs-on: namespace-profile-ghostty-sm
+    env:
+      GHOSTTY_VERSION: ${{ needs.setup.outputs.version }}
+    steps:
+      - name: Download macOS Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: macos
+
+      - name: Download Sparkle Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: sparkle
+
+      - name: Download Source Tarball Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: source-tarball
+
+      # Upload all of our files EXCEPT the appcast. The appcast triggers
+      # updates in clients and we don't want to do that until we're
+      # sure these are uploaded.
+      - name: Prep Files
+        run: |
+          mkdir blob
+          mkdir -p blob/${GHOSTTY_VERSION}
+          mv ghostty-source.tar.gz blob/${GHOSTTY_VERSION}/ghostty-source.tar.gz
+          mv ghostty-source.tar.gz.minisig blob/${GHOSTTY_VERSION}/ghostty-source.tar.gz.minisig
+          mv ghostty-macos-universal.zip blob/${GHOSTTY_VERSION}/ghostty-macos-universal.zip
+          mv ghostty-macos-universal-dsym.zip blob/${GHOSTTY_VERSION}/ghostty-macos-universal-dsym.zip
+      - name: Upload to R2
+        uses: ryand56/r2-upload-action@latest
+        with:
+          r2-account-id: ${{ secrets.CF_R2_RELEASE_ACCOUNT_ID }}
+          r2-access-key-id: ${{ secrets.CF_R2_RELEASE_AWS_KEY }}
+          r2-secret-access-key: ${{ secrets.CF_R2_RELEASE_SECRET_KEY }}
+          r2-bucket: ghostty-release
+          source-dir: blob
+          destination-dir: ./
+
+      - name: Prep Appcast
+        run: |
+          rm -rf blob
+          mkdir blob
+          mv appcast.xml blob/appcast.xml
+      - name: Upload Appcast to R2
+        uses: ryand56/r2-upload-action@latest
+        with:
+          r2-account-id: ${{ secrets.CF_R2_RELEASE_ACCOUNT_ID }}
+          r2-access-key-id: ${{ secrets.CF_R2_RELEASE_AWS_KEY }}
+          r2-secret-access-key: ${{ secrets.CF_R2_RELEASE_SECRET_KEY }}
+          r2-bucket: ghostty-release
+          source-dir: blob
+          destination-dir: ./
--- a/PACKAGING.md
+++ b/PACKAGING.md
@ -14,17 +14,29 @@ package Ghostty for distribution.

 ## Source Tarballs

-Source tarballs with stable checksums are available on the
-[GitHub releases page](https://github.com/ghostty-org/ghostty/releases).
-Use the `ghostty-source.tar.gz` asset and _not the GitHub auto-generated
-source tarball_.
+Source tarballs with stable checksums are available for tagged releases
+at `release.files.ghostty.org` in the following URL format where
+`VERSION` is the version number with no prefix such as `1.0.0`:

-Signature files are signed with [minisign](https://jedisct1.github.io/minisign/) using the following public key:
+```
+https://release.files.ghostty.org/VERSION/ghostty-source.tar.gz
+https://release.files.ghostty.org/VERSION/ghostty-source.tar.gz.minisig
+```
+
+Signature files are signed with
+[minisign](https://jedisct1.github.io/minisign/)
+using the following public key:

 ```
 RWQlAjJC23149WL2sEpT/l0QKy7hMIFhYdQOFy0Z7z7PbneUgvlsnYcV
 ```

+**Tip source tarballs** are available on the
+[GitHub releases page](https://github.com/ghostty-org/ghostty/releases/tag/tip).
+Use the `ghostty-source.tar.gz` asset and _not the GitHub auto-generated
+source tarball_. These tarballs are generated for every commit to
+the `main` branch and are not associated with a specific version.
+
 ## Zig Version

 [Zig](https://ziglang.org) is required to build Ghostty. Prior to Zig 1.0,
--- a/dist/macos/update_appcast_tag.py
+++ b/dist/macos/update_appcast_tag.py
@ -0,0 +1,105 @@
+"""
+This script is used to update the appcast.xml file for tagged
+Ghostty releases.
+
+This expects the following files in the current directory:
+    - sign_update.txt - contains the output from "sign_update" in the Sparkle
+      framework for the current build.
+    - appcast.xml - the existing appcast file.
+
+And the following environment variables to be set:
+    - GHOSTTY_VERSION - the version number (X.Y.Z format)
+    - GHOSTTY_BUILD - the build number
+    - GHOSTTY_COMMIT - the commit hash
+
+The script will output a new appcast file called appcast_new.xml.
+"""
+
+import os
+import xml.etree.ElementTree as ET
+from datetime import datetime, timezone
+
+now = datetime.now(timezone.utc)
+version = os.environ["GHOSTTY_VERSION"]
+build = os.environ["GHOSTTY_BUILD"]
+commit = os.environ["GHOSTTY_COMMIT"]
+commit_long = os.environ["GHOSTTY_COMMIT_LONG"]
+repo = "https://github.com/ghostty-org/ghostty"
+
+# Read our sign_update output
+with open("sign_update.txt", "r") as f:
+    # format is a=b b=c etc. create a map of this. values may contain equal
+    # signs, so we can't just split on equal signs.
+    attrs = {}
+    for pair in f.read().split(" "):
+        key, value = pair.split("=", 1)
+        value = value.strip()
+        if value[0] == '"':
+            value = value[1:-1]
+        attrs[key] = value
+
+# We need to register our namespaces before reading or writing any files.
+namespaces = { "sparkle": "http://www.andymatuschak.org/xml-namespaces/sparkle" }
+for prefix, uri in namespaces.items():
+    ET.register_namespace(prefix, uri)
+
+# Open our existing appcast and find the channel element. This is where
+# we'll add our new item.
+et = ET.parse('appcast.xml')
+channel = et.find("channel")
+
+# Remove any items with the same version. If we have multiple items with
+# the same version, Sparkle will report invalid signatures if it picks
+# the wrong one when updating.
+for item in channel.findall("item"):
+    version = item.find("sparkle:version", namespaces)
+    if version is not None and version.text == build:
+        channel.remove(item)
+
+    # We also remove any item that doesn't have a pubDate. This should
+    # never happen but it prevents us from having to deal with it later.
+    if item.find("pubDate") is None:
+        channel.remove(item)
+
+# Prune the oldest items if we have more than a limit.
+prune_amount = 15
+pubdate_format = "%a, %d %b %Y %H:%M:%S %z"
+items = channel.findall("item")
+items.sort(key=lambda item: datetime.strptime(item.find("pubDate").text, pubdate_format))
+if len(items) > prune_amount:
+    for item in items[:-prune_amount]:
+        channel.remove(item)
+
+# Create the item using some absolutely terrible XML manipulation.
+item = ET.SubElement(channel, "item")
+elem = ET.SubElement(item, "title")
+elem.text = f"Build {build}"
+elem = ET.SubElement(item, "pubDate")
+elem.text = now.strftime(pubdate_format)
+elem = ET.SubElement(item, "sparkle:version")
+elem.text = build
+elem = ET.SubElement(item, "sparkle:shortVersionString")
+elem.text = f"{commit} ({now.strftime('%Y-%m-%d')})"
+elem = ET.SubElement(item, "sparkle:minimumSystemVersion")
+elem.text = "13.0.0"
+elem = ET.SubElement(item, "description")
+elem.text = f"""
+<h1>Ghostty v{version}</h1>
+<p>
+We don't currently generate release notes for auto-updates.
+You can view the complete changelog and release notes on
+the <a href="https://ghostty.org">Ghostty website</a>.
+</p>
+<p>
+This release was built from commit <code><a href="{repo}/commits/{commit_long}">{commit}</a></code>
+on {now.strftime('%Y-%m-%d')}.
+</p>
+"""
+elem = ET.SubElement(item, "enclosure")
+elem.set("url", f"https://release.files.ghostty.org/{version}/ghostty-macos-universal.zip")
+elem.set("type", "application/octet-stream")
+for key, value in attrs.items():
+    elem.set(key, value)
+
+# Output the new appcast.
+et.write("appcast_new.xml", xml_declaration=True, encoding="utf-8")
--- a/dist/macos/update_appcast_tip.py
+++ b/dist/macos/update_appcast_tip.py
@ -80,7 +80,7 @@ elem.text = build
 elem = ET.SubElement(item, "sparkle:shortVersionString")
 elem.text = f"{commit} ({now.strftime('%Y-%m-%d')})"
 elem = ET.SubElement(item, "sparkle:minimumSystemVersion")
-elem.text = "12.0.0"
+elem.text = "13.0.0"
 elem = ET.SubElement(item, "description")
 elem.text = f"""
 <p>
--- a/macos/Ghostty-Info.plist
+++ b/macos/Ghostty-Info.plist
@ -42,6 +42,8 @@
 			</array>
 		</dict>
 	</array>
+	<key>GhosttyBuild</key>
+	<string></string>
 	<key>GhosttyCommit</key>
 	<string></string>
 	<key>LSEnvironment</key>