Build TUI Binaries workflow (VRSEN/OpenSwarm)

The Build TUI Binaries workflow from VRSEN/OpenSwarm, explained and optimized by Latchkey.

CI health: C - fair

Point runs-on at Latchkey and get caching, job timeouts, self-healing for flaky steps, and up to 58% lower cost, applied automatically.

Grade your own workflow free or run it on Latchkey →

Source: VRSEN/OpenSwarm.github/workflows/build-tui.ymlLicense MITView source

What it does

This is the Build TUI Binaries workflow from the VRSEN/OpenSwarm repository, a real project running GitHub Actions. It is shown here with attribution under its MIT license.

Below, Latchkey shows a faster, safer version produced by its optimization engine.

The workflow

workflow (.yml)

name: Build TUI Binaries

on:
  workflow_dispatch:
    inputs:
      version:
        description: "Release version. Defaults to package.json."
        required: false
        type: string
  push:
    tags:
      - 'v*.*.*'

concurrency: release-${{ github.ref }}

permissions:
  contents: read

jobs:
  prepare:
    runs-on: ubuntu-latest
    outputs:
      release_version: ${{ steps.release.outputs.release_version }}
      release_tag: ${{ steps.release.outputs.release_tag }}
      is_prerelease: ${{ steps.release.outputs.is_prerelease }}
      npm_tag: ${{ steps.release.outputs.npm_tag }}
      target_commitish: ${{ steps.release.outputs.target_commitish }}
      agentswarm_cli_version: ${{ steps.release.outputs.agentswarm_cli_version }}
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Resolve release version
        id: release
        shell: bash
        env:
          INPUT_VERSION: ${{ github.event.inputs.version || '' }}
        run: |
          set -euo pipefail

          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" && "${GITHUB_REF_NAME}" != "main" ]]; then
            echo "Manual releases must run from main. Current ref: ${GITHUB_REF_NAME}" >&2
            exit 1
          fi

          package_version="$(node -p "require('./package.json').version")"
          lock_version="$(node -p "require('./package-lock.json').packages[''].version")"
          agentswarm_cli_version="$(node -p "require('./package.json').dependencies['@vrsen/agentswarm']")"
          python_version="$(python3 - <<'PY'
          import tomllib
          with open("pyproject.toml", "rb") as handle:
              print(tomllib.load(handle)["project"]["version"])
          PY
          )"

          input_version="$INPUT_VERSION"
          input_version="${input_version#v}"
          release_version="${input_version:-$package_version}"

          if [[ ! "$release_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z][0-9A-Za-z.-]*)?$ ]]; then
            echo "Release version must be semver X.Y.Z or X.Y.Z-prerelease, got: $release_version" >&2
            exit 1
          fi

          if [[ ! "$agentswarm_cli_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z][0-9A-Za-z.-]*)?$ ]]; then
            echo "@vrsen/agentswarm must use an exact AgentSwarm CLI version, got: $agentswarm_cli_version" >&2
            exit 1
          fi

          if [[ "$package_version" != "$release_version" ]]; then
            echo "package.json version ($package_version) must match release version ($release_version)." >&2
            exit 1
          fi

          if [[ "$lock_version" != "$release_version" ]]; then
            echo "package-lock.json version ($lock_version) must match release version ($release_version)." >&2
            exit 1
          fi

          if [[ "$python_version" != "$release_version" ]]; then
            echo "pyproject.toml version ($python_version) must match release version ($release_version)." >&2
            exit 1
          fi

          release_tag="v$release_version"
          is_prerelease=false
          npm_tag=latest
          if [[ "$release_version" == *-* ]]; then
            is_prerelease=true
            npm_tag="${release_version#*-}"
            npm_tag="${npm_tag%%.*}"
          fi

          if [[ "${GITHUB_REF_TYPE}" == "tag" && "${GITHUB_REF_NAME}" != "$release_tag" ]]; then
            echo "Tag ${GITHUB_REF_NAME} does not match package version $release_version." >&2
            exit 1
          fi

          {
            echo "release_version=$release_version"
            echo "release_tag=$release_tag"
            echo "is_prerelease=$is_prerelease"
            echo "npm_tag=$npm_tag"
            echo "target_commitish=$GITHUB_SHA"
            echo "agentswarm_cli_version=$agentswarm_cli_version"
          } >> "$GITHUB_OUTPUT"

  build:
    needs: prepare
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Extract official AgentSwarm binaries
        shell: bash
        run: node scripts/extract-agentswarm-binaries.mjs "${{ needs.prepare.outputs.agentswarm_cli_version }}" dist

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: agentswarm-binaries
          path: dist/*
          if-no-files-found: error

  release:
    needs:
      - prepare
      - build
    if: github.repository == 'VRSEN/OpenSwarm'
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/download-artifact@v4
        with:
          path: dist
          merge-multiple: true

      - name: Create GitHub Release
        shell: bash
        env:
          GH_REPO: ${{ github.repository }}
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: ${{ needs.prepare.outputs.release_tag }}
          IS_PRERELEASE: ${{ needs.prepare.outputs.is_prerelease }}
          TARGET_COMMITISH: ${{ needs.prepare.outputs.target_commitish }}
        run: |
          set -euo pipefail

          mapfile -t files < <(find dist -type f | sort)
          if (( ${#files[@]} == 0 )); then
            echo "No release assets found in dist/." >&2
            exit 1
          fi

          create_flags=(--draft --generate-notes --target "$TARGET_COMMITISH" --title "$RELEASE_TAG")
          edit_flags=(--draft=false)
          if [[ "$IS_PRERELEASE" == "true" ]]; then
            create_flags+=(--prerelease --latest=false)
            edit_flags+=(--prerelease)
          else
            create_flags+=(--latest)
            edit_flags+=(--latest)
          fi

          if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
            gh release upload "$RELEASE_TAG" "${files[@]}" --clobber
          else
            gh release create "$RELEASE_TAG" "${files[@]}" "${create_flags[@]}"
          fi

          gh release edit "$RELEASE_TAG" "${edit_flags[@]}"

  publish-npm:
    needs:
      - prepare
      - release
    if: github.repository == 'VRSEN/OpenSwarm'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    env:
      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      NPM_CONFIG_PROVENANCE: false
      NPM_TAG: ${{ needs.prepare.outputs.npm_tag }}
    steps:
      - name: Checkout release tag
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.prepare.outputs.release_tag }}

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org"

      - name: Validate release metadata
        shell: bash
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: ${{ needs.prepare.outputs.release_tag }}
          RELEASE_VERSION: ${{ needs.prepare.outputs.release_version }}
        run: |
          set -euo pipefail

          if [[ -z "${NODE_AUTH_TOKEN}" ]]; then
            echo "NPM_TOKEN is required to publish to npm." >&2
            exit 1
          fi

          if [[ "$RELEASE_TAG" != "v$RELEASE_VERSION" ]]; then
            echo "Release tag ($RELEASE_TAG) must match release version ($RELEASE_VERSION)." >&2
            exit 1
          fi

          package_version="$(node -p "require('./package.json').version")"
          lock_version="$(node -p "require('./package-lock.json').packages[''].version")"
          python_version="$(python3 - <<'PY'
          import tomllib
          with open("pyproject.toml", "rb") as handle:
              print(tomllib.load(handle)["project"]["version"])
          PY
          )"

          if [[ "$package_version" != "$RELEASE_VERSION" || "$lock_version" != "$RELEASE_VERSION" || "$python_version" != "$RELEASE_VERSION" ]]; then
            echo "Release tag, package.json, package-lock.json, and pyproject.toml versions must match." >&2
            echo "tag=$RELEASE_VERSION package=$package_version lock=$lock_version pyproject=$python_version" >&2
            exit 1
          fi

          mapfile -t assets < <(gh release view "$RELEASE_TAG" --json assets --jq '.assets[].name' | sort)
          required_assets=(
            agentswarm-darwin-arm64
            agentswarm-darwin-x64
            agentswarm-darwin-x64-baseline
            agentswarm-linux-arm64
            agentswarm-linux-arm64-musl
            agentswarm-linux-x64
            agentswarm-linux-x64-baseline
            agentswarm-linux-x64-baseline-musl
            agentswarm-linux-x64-musl
            agentswarm-windows-arm64.exe
            agentswarm-windows-x64.exe
            agentswarm-windows-x64-baseline.exe
          )

          for required in "${required_assets[@]}"; do
            if ! printf '%s\n' "${assets[@]}" | grep -Fxq "$required"; then
              echo "Release $RELEASE_TAG is missing required asset: $required" >&2
              exit 1
            fi
          done

      - name: Install dependencies
        run: npm ci

      - name: Download platform release assets
        shell: bash
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: ${{ needs.prepare.outputs.release_tag }}
        run: |
          set -euo pipefail
          mkdir -p dist
          gh release download "$RELEASE_TAG" --dir dist --clobber

      - name: Pack platform npm packages
        run: node scripts/package-platform-binaries.mjs dist platform-packages

      - name: Publish platform npm packages
        shell: bash
        run: |
          set -euo pipefail
          mapfile -t packages < <(find platform-packages -maxdepth 1 -name '*.tgz' -type f | sort)
          if (( ${#packages[@]} != 12 )); then
            echo "Expected 12 OpenSwarm platform packages, got ${#packages[@]}." >&2
            exit 1
          fi
          for package in "${packages[@]}"; do
            pkg_id="$(tar -xOf "$package" package/package.json | node -e "const fs=require('fs'); const pkg=JSON.parse(fs.readFileSync(0,'utf8')); console.log(pkg.name+'@'+pkg.version)")"
            if npm view "$pkg_id" version >/dev/null 2>&1; then
              echo "Skipping $pkg_id; already published."
              continue
            fi
            npm publish "./$package" --access public --tag "$NPM_TAG"
          done

      - name: Publish npm package
        run: npm publish --access public --tag "$NPM_TAG"

The same workflow, on Latchkey

Estimated ~20% faster on cache hits, plus fewer wasted runs and a safer supply chain. Added and changed lines are highlighted.

name: Build TUI Binaries
 
on:
  workflow_dispatch:
    inputs:
      version:
        description: "Release version. Defaults to package.json."
        required: false
        type: string
  push:
    tags:
      - 'v*.*.*'
 
concurrency: release-${{ github.ref }}
 
permissions:
  contents: read
 
jobs:
  prepare:
    timeout-minutes: 30
    runs-on: latchkey-small
    outputs:
      release_version: ${{ steps.release.outputs.release_version }}
      release_tag: ${{ steps.release.outputs.release_tag }}
      is_prerelease: ${{ steps.release.outputs.is_prerelease }}
      npm_tag: ${{ steps.release.outputs.npm_tag }}
      target_commitish: ${{ steps.release.outputs.target_commitish }}
      agentswarm_cli_version: ${{ steps.release.outputs.agentswarm_cli_version }}
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          cache: 'npm'
          node-version: 20
 
      - name: Resolve release version
        id: release
        shell: bash
        env:
          INPUT_VERSION: ${{ github.event.inputs.version || '' }}
        run: |
          set -euo pipefail
 
          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" && "${GITHUB_REF_NAME}" != "main" ]]; then
            echo "Manual releases must run from main. Current ref: ${GITHUB_REF_NAME}" >&2
            exit 1
          fi
 
          package_version="$(node -p "require('./package.json').version")"
          lock_version="$(node -p "require('./package-lock.json').packages[''].version")"
          agentswarm_cli_version="$(node -p "require('./package.json').dependencies['@vrsen/agentswarm']")"
          python_version="$(python3 - <<'PY'
          import tomllib
          with open("pyproject.toml", "rb") as handle:
              print(tomllib.load(handle)["project"]["version"])
          PY
          )"
 
          input_version="$INPUT_VERSION"
          input_version="${input_version#v}"
          release_version="${input_version:-$package_version}"
 
          if [[ ! "$release_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z][0-9A-Za-z.-]*)?$ ]]; then
            echo "Release version must be semver X.Y.Z or X.Y.Z-prerelease, got: $release_version" >&2
            exit 1
          fi
 
          if [[ ! "$agentswarm_cli_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z][0-9A-Za-z.-]*)?$ ]]; then
            echo "@vrsen/agentswarm must use an exact AgentSwarm CLI version, got: $agentswarm_cli_version" >&2
            exit 1
          fi
 
          if [[ "$package_version" != "$release_version" ]]; then
            echo "package.json version ($package_version) must match release version ($release_version)." >&2
            exit 1
          fi
 
          if [[ "$lock_version" != "$release_version" ]]; then
            echo "package-lock.json version ($lock_version) must match release version ($release_version)." >&2
            exit 1
          fi
 
          if [[ "$python_version" != "$release_version" ]]; then
            echo "pyproject.toml version ($python_version) must match release version ($release_version)." >&2
            exit 1
          fi
 
          release_tag="v$release_version"
          is_prerelease=false
          npm_tag=latest
          if [[ "$release_version" == *-* ]]; then
            is_prerelease=true
            npm_tag="${release_version#*-}"
            npm_tag="${npm_tag%%.*}"
          fi
 
          if [[ "${GITHUB_REF_TYPE}" == "tag" && "${GITHUB_REF_NAME}" != "$release_tag" ]]; then
            echo "Tag ${GITHUB_REF_NAME} does not match package version $release_version." >&2
            exit 1
          fi
 
          {
            echo "release_version=$release_version"
            echo "release_tag=$release_tag"
            echo "is_prerelease=$is_prerelease"
            echo "npm_tag=$npm_tag"
            echo "target_commitish=$GITHUB_SHA"
            echo "agentswarm_cli_version=$agentswarm_cli_version"
          } >> "$GITHUB_OUTPUT"
 
  build:
    timeout-minutes: 30
    needs: prepare
    runs-on: latchkey-small
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          cache: 'npm'
          node-version: 20
 
      - name: Extract official AgentSwarm binaries
        shell: bash
        run: node scripts/extract-agentswarm-binaries.mjs "${{ needs.prepare.outputs.agentswarm_cli_version }}" dist
 
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: agentswarm-binaries
          path: dist/*
          if-no-files-found: error
 
  release:
    timeout-minutes: 30
    needs:
      - prepare
      - build
    if: github.repository == 'VRSEN/OpenSwarm'
    runs-on: latchkey-small
    permissions:
      contents: write
    steps:
      - uses: actions/download-artifact@v4
        with:
          path: dist
          merge-multiple: true
 
      - name: Create GitHub Release
        shell: bash
        env:
          GH_REPO: ${{ github.repository }}
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: ${{ needs.prepare.outputs.release_tag }}
          IS_PRERELEASE: ${{ needs.prepare.outputs.is_prerelease }}
          TARGET_COMMITISH: ${{ needs.prepare.outputs.target_commitish }}
        run: |
          set -euo pipefail
 
          mapfile -t files < <(find dist -type f | sort)
          if (( ${#files[@]} == 0 )); then
            echo "No release assets found in dist/." >&2
            exit 1
          fi
 
          create_flags=(--draft --generate-notes --target "$TARGET_COMMITISH" --title "$RELEASE_TAG")
          edit_flags=(--draft=false)
          if [[ "$IS_PRERELEASE" == "true" ]]; then
            create_flags+=(--prerelease --latest=false)
            edit_flags+=(--prerelease)
          else
            create_flags+=(--latest)
            edit_flags+=(--latest)
          fi
 
          if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
            gh release upload "$RELEASE_TAG" "${files[@]}" --clobber
          else
            gh release create "$RELEASE_TAG" "${files[@]}" "${create_flags[@]}"
          fi
 
          gh release edit "$RELEASE_TAG" "${edit_flags[@]}"
 
  publish-npm:
    timeout-minutes: 30
    needs:
      - prepare
      - release
    if: github.repository == 'VRSEN/OpenSwarm'
    runs-on: latchkey-small
    permissions:
      contents: read
    env:
      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      NPM_CONFIG_PROVENANCE: false
      NPM_TAG: ${{ needs.prepare.outputs.npm_tag }}
    steps:
      - name: Checkout release tag
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.prepare.outputs.release_tag }}
 
      - uses: actions/setup-node@v4
        with:
          cache: 'npm'
          node-version: 20
          registry-url: "https://registry.npmjs.org"
 
      - name: Validate release metadata
        shell: bash
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: ${{ needs.prepare.outputs.release_tag }}
          RELEASE_VERSION: ${{ needs.prepare.outputs.release_version }}
        run: |
          set -euo pipefail
 
          if [[ -z "${NODE_AUTH_TOKEN}" ]]; then
            echo "NPM_TOKEN is required to publish to npm." >&2
            exit 1
          fi
 
          if [[ "$RELEASE_TAG" != "v$RELEASE_VERSION" ]]; then
            echo "Release tag ($RELEASE_TAG) must match release version ($RELEASE_VERSION)." >&2
            exit 1
          fi
 
          package_version="$(node -p "require('./package.json').version")"
          lock_version="$(node -p "require('./package-lock.json').packages[''].version")"
          python_version="$(python3 - <<'PY'
          import tomllib
          with open("pyproject.toml", "rb") as handle:
              print(tomllib.load(handle)["project"]["version"])
          PY
          )"
 
          if [[ "$package_version" != "$RELEASE_VERSION" || "$lock_version" != "$RELEASE_VERSION" || "$python_version" != "$RELEASE_VERSION" ]]; then
            echo "Release tag, package.json, package-lock.json, and pyproject.toml versions must match." >&2
            echo "tag=$RELEASE_VERSION package=$package_version lock=$lock_version pyproject=$python_version" >&2
            exit 1
          fi
 
          mapfile -t assets < <(gh release view "$RELEASE_TAG" --json assets --jq '.assets[].name' | sort)
          required_assets=(
            agentswarm-darwin-arm64
            agentswarm-darwin-x64
            agentswarm-darwin-x64-baseline
            agentswarm-linux-arm64
            agentswarm-linux-arm64-musl
            agentswarm-linux-x64
            agentswarm-linux-x64-baseline
            agentswarm-linux-x64-baseline-musl
            agentswarm-linux-x64-musl
            agentswarm-windows-arm64.exe
            agentswarm-windows-x64.exe
            agentswarm-windows-x64-baseline.exe
          )
 
          for required in "${required_assets[@]}"; do
            if ! printf '%s\n' "${assets[@]}" | grep -Fxq "$required"; then
              echo "Release $RELEASE_TAG is missing required asset: $required" >&2
              exit 1
            fi
          done
 
      - name: Install dependencies
        run: npm ci
 
      - name: Download platform release assets
        shell: bash
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: ${{ needs.prepare.outputs.release_tag }}
        run: |
          set -euo pipefail
          mkdir -p dist
          gh release download "$RELEASE_TAG" --dir dist --clobber
 
      - name: Pack platform npm packages
        run: node scripts/package-platform-binaries.mjs dist platform-packages
 
      - name: Publish platform npm packages
        shell: bash
        run: |
          set -euo pipefail
          mapfile -t packages < <(find platform-packages -maxdepth 1 -name '*.tgz' -type f | sort)
          if (( ${#packages[@]} != 12 )); then
            echo "Expected 12 OpenSwarm platform packages, got ${#packages[@]}." >&2
            exit 1
          fi
          for package in "${packages[@]}"; do
            pkg_id="$(tar -xOf "$package" package/package.json | node -e "const fs=require('fs'); const pkg=JSON.parse(fs.readFileSync(0,'utf8')); console.log(pkg.name+'@'+pkg.version)")"
            if npm view "$pkg_id" version >/dev/null 2>&1; then
              echo "Skipping $pkg_id; already published."
              continue
            fi
            npm publish "./$package" --access public --tag "$NPM_TAG"
          done
 
      - name: Publish npm package
        run: npm publish --access public --tag "$NPM_TAG"

What changed

Run on Latchkey managed runners with one line (runs-on), which apply the fixes below automatically and self-heal transient failures. This example uses latchkey-small; pick the runner size that fits the job.
Cache dependency installs on the setup step so they are served from cache.
Add a job timeout so a hung step cannot burn hours of runner time.

What Latchkey heals here

This workflow has steps that commonly fail on transient issues (network, registries, flaky browsers). On Latchkey managed runners they are detected, retried, and self-healed instead of failing your build:

Dependency installs

This workflow runs 4 jobs per trigger. On Latchkey the same minutes cost up to 58% less than GitHub-hosted, with zero queue time.

Actions used in this workflow

actions/checkout actions/setup-node actions/upload-artifact actions/download-artifact