release.yml

name: Release

# MANUAL ONLY. Nothing about a money-moving tool should ship on a merge.
#
# The workflow deliberately does NOT bump the version itself: a version bump is a human decision
# and belongs in a reviewed PR. This job asserts that `pyproject.toml` already carries the version
# being released and fails loudly otherwise, so CI never writes to `main`.
on:
  workflow_dispatch:
    inputs:
      version:
        description: "Semver to release, without a leading v (e.g. 0.2.0). Must already match pyproject.toml."
        required: true
        type: string
      desktop:
        description: "Desktop artifacts. 'build' produces and smoke-tests them as workflow artifacts only. 'publish-unsigned' also attaches them to the release -- they are NOT code-signed, so macOS Gatekeeper and Windows SmartScreen will warn; the option is named for what it does so it cannot be chosen without reading it. 'skip' does neither."
        required: true
        default: build
        type: choice
        options: [build, publish-unsigned, skip]

permissions:
  contents: write # create the tag and the release
  pull-requests: read # "Compose release notes" reads merged PRs (list-PRs-for-commit + get-PR);
  # without this the default GITHUB_TOKEN gets 403 "Resource not accessible by integration".

jobs:
  release:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0 # tags, and a real commit history for the build stamp

      - name: Validate the version input
        run: |
          set -euo pipefail
          VERSION="${{ inputs.version }}"
          if ! printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
            echo "::error::'$VERSION' is not a bare semver (expected N.N.N, no leading v)"; exit 1
          fi
          PYPROJECT="$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)"
          if [ "$PYPROJECT" != "$VERSION" ]; then
            echo "::error::pyproject.toml says '$PYPROJECT' but you asked to release '$VERSION'."
            echo "::error::Bump the version in a reviewed PR first -- this workflow will not write to main."
            exit 1
          fi
          if git rev-parse "v$VERSION" >/dev/null 2>&1; then
            echo "::error::tag v$VERSION already exists -- releases are immutable"; exit 1
          fi

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      - name: Set up Python
        run: uv python install   # version comes from .python-version; never pin it here twice

      # #424: the 0.10.0 release failed five steps late because a version bump moved seven
      # pyproject.toml files and not the eighth thing -- uv.lock. `uv sync` below silently
      # re-locks a stale checkout, the stamp then records a dirty tree, and the failure only
      # surfaces as "artifact reports a dirty tree", pointing at keel/version.py and the
      # stamp step instead of the lockfile, after lint/types/tests/build have all run.
      # `--check` re-resolves against the manifests and exits non-zero WITHOUT writing, so
      # this must come before anything that can mutate the tree.
      - name: The lockfile must already be current
        run: |
          set -euo pipefail
          if ! uv lock --check; then
            echo "::error::uv.lock is stale for this pyproject -- run 'uv lock' locally and commit the result with the version bump. (A stale lock is otherwise discovered five steps later as 'artifact reports a dirty tree'.)"
            exit 1
          fi

      - name: Sync dependencies
        run: uv sync --all-extras --dev

      # The release gate. A red suite must never produce an artifact that could touch funds.
      - name: Lint
        run: uv run ruff check keel tests packages

      # Re-run here rather than trusting CI's: this workflow is dispatched against whatever
      # `main` is at the time, which need not be the commit any CI run went green on.
      - name: Type-check
        run: uv run mypy

      - name: Test
        run: uv run pytest -q

      # Stamp the build so an INSTALLED artifact can identify itself with no git and no repo
      # present. `keel/version.py` prefers this over shelling out to git.
      - name: Stamp build info
        run: |
          set -euo pipefail
          COMMIT="$(git rev-parse --short=12 HEAD)"
          cat > keel/_build_info.py <<EOF
          """Generated by .github/workflows/release.yml. Do not edit or commit."""

          VERSION = "${{ inputs.version }}"
          COMMIT = "$COMMIT"
          DIRTY = False
          EOF
          echo "stamped $COMMIT"

      # --all-packages: `keel` depends on the workspace members (keel-core, keel-broker-*),
      # which are NOT published anywhere. A lone `keel` wheel is uninstallable.
      - name: Build
        run: uv build --all-packages

      - name: Verify the artifact identifies itself
        run: |
          set -euo pipefail
          # Must be the PINNED interpreter, not the runner's default `python`. The wheel
          # carries `Requires-Python: >=3.14.4`, and pip enforces that even for an explicit
          # local wheel path -- a default-python venv fails here with "requires a different
          # Python". --seed provides the pip that the install below uses.
          uv venv --seed --python "$(cat .python-version)" /tmp/verify
          # Install by explicit PATH, never by name. The name `keel` belongs to an unrelated
          # project on PyPI, so a name-based install can silently fetch a stranger's package --
          # unacceptable for a tool that places orders. --find-links resolves the workspace
          # members from the same dist/ directory.
          /tmp/verify/bin/pip install --quiet --find-links dist dist/keel_trader-${{ inputs.version }}-py3-none-any.whl
          OUT="$(/tmp/verify/bin/keel --version)"
          echo "$OUT"
          printf '%s' "$OUT" | grep -q "${{ inputs.version }}" || {
            echo "::error::artifact does not report the released version"; exit 1; }
          printf '%s' "$OUT" | grep -q "release" || {
            echo "::error::artifact is not stamped as a release build"; exit 1; }
          printf '%s' "$OUT" | grep -q "DIRTY" && {
            echo "::error::artifact reports a dirty tree"; exit 1; } || true
          # `--version` speaks for the keel-trader distribution ALONE, so it cannot see a
          # sibling left behind at an older version -- the failure that had `~/keel` running
          # keel-trader 0.5.7 against keel-core 0.5.5. `keel versions` checks every keel
          # distribution in the venv and exits non-zero when they disagree, which also proves
          # the `==` pins in the wheels actually pulled the siblings from dist/.
          /tmp/verify/bin/keel versions || {
            echo "::error::the installed wheels do not agree on a version"; exit 1; }

      # The release ships a ready-for-live config as a downloadable asset. It must be in
      # `confirm` mode: a config that trades unattended straight off a download is exactly what
      # this project refuses to ship. Fail the release loudly rather than publish an armed config.
      - name: Verify and stage the live config asset
        run: |
          set -euo pipefail
          uv run python -c "from keel.config import load_config; m = load_config('keel/templates/config.live.yaml').auto_trade.mode; assert m == 'confirm', f'live config must be confirm mode, got {m!r}'; print('live config OK: mode=confirm')"
          cp keel/templates/config.live.yaml config.yaml

      - name: Tag
        run: |
          set -euo pipefail
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git tag -a "v${{ inputs.version }}" -m "keel v${{ inputs.version }}"
          git push origin "v${{ inputs.version }}"

      - name: Compose release notes
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
          # The change list INLINES each merged PR's body -- a reader should never have to click
          # through to a PR to learn what shipped. Grouping still comes from .github/release.yml.
          PREV="$(git describe --tags --abbrev=0 "v${{ inputs.version }}^" 2>/dev/null || true)"
          if [ -n "$PREV" ]; then
            RANGE="$PREV..HEAD"
          else
            # First release: no previous tag, so walk from the start of history.
            RANGE="HEAD"
          fi

          # Every PR whose commits land in this range, de-duplicated.
          : > /tmp/pr-numbers.txt
          for sha in $(git log --format=%H "$RANGE"); do
            # `grep '^[0-9]+$'` guards the file against ever holding anything but a bare PR
            # number: if a `gh api` call errors (e.g. a 403), its body must never be treated as
            # a "PR number" and fed back into a URL. Belt-and-braces with the numeric loop below.
            gh api "repos/${{ github.repository }}/commits/$sha/pulls" \
              -q '.[].number' 2>/dev/null | grep -E '^[0-9]+$' >> /tmp/pr-numbers.txt || true
          done
          sort -u -n /tmp/pr-numbers.txt -o /tmp/pr-numbers.txt
          echo "found $(wc -l < /tmp/pr-numbers.txt) PRs in $RANGE"

          # Fetch each PR's title/body/labels, then compose. jq -s folds the stream into an array.
          : > /tmp/prs.ndjson
          while read -r n; do
            case "$n" in ''|*[!0-9]*) continue ;; esac  # numeric PR numbers only
            gh api "repos/${{ github.repository }}/pulls/$n" \
              -q '{number:.number,title:.title,body:(.body // ""),labels:[.labels[].name]}' \
              >> /tmp/prs.ndjson
          done < /tmp/pr-numbers.txt
          jq -s '.' /tmp/prs.ndjson > /tmp/prs.json
          GENERATED="$(uv run python scripts/release_notes.py < /tmp/prs.json)"
          {
            echo "Built from $(git rev-parse --short=12 HEAD). Version binds to this hash:"
            echo "\`keel --version\` reports \`keel ${{ inputs.version }}+$(git rev-parse --short=12 HEAD) [release]\`."
            echo
            echo "## Install"
            echo
            echo "Download **all** wheels from this release into one directory, then install the"
            echo "\`keel_trader\` wheel **by path**:"
            echo
            echo '    pip install --find-links . ./keel_trader-${{ inputs.version }}-py3-none-any.whl'
            echo "    keel versions"
            echo
            echo "\`keel versions\` — not \`keel --version\` — is the check: it reports **every**"
            echo "keel distribution in the venv and exits non-zero if a sibling was left behind at"
            echo "an older version, which \`--version\` cannot see. Upgrading an existing"
            echo "deployment: see \"Deploying a new version\" in the README."
            echo
            echo "⚠️ **Never install by bare name.** The distribution is \`keel-trader\`; the name"
            echo "\`keel\` on PyPI belongs to an unrelated project, so \`pip install keel\` fetches"
            echo "someone else's package. A build reporting **DIRTY** or **[checkout]** is not this"
            echo "release and must not be run against live funds."
            echo
            echo "## Configure"
            echo
            echo "\`config.yaml\` is attached to this release: the production config, in"
            echo "\`auto_trade.mode: confirm\` — keel previews every order and waits for your"
            echo "approval. Drop it beside the install (or run \`keel init-config --live\`), put"
            echo "your CDP key in a git-ignored \`.env\`, then:"
            echo
            echo '    keel migrate     # existing database: apply schema migrations'
            echo '    keel init        # fresh deployment: write config + seed candidate rules'
            echo
            echo "Seeded rules start as \`candidate\` and trade nothing until you promote them."
            echo
            if [ "${{ inputs.desktop }}" = "publish-unsigned" ]; then
              echo "## Desktop app (macOS / Windows)"
              echo
              echo "⚠️ **These builds are not code-signed, so your computer will warn you.**"
              echo "Apple's certificate is \$99/yr and Azure Trusted Signing is ~\$120/yr, and"
              echo "keel cannot currently afford either. There is no cheaper tier and no free"
              echo "open-source option on either platform. (Windows is worse value than it looks:"
              echo "since 2024 even an EV certificate no longer grants an instant SmartScreen"
              echo "pass — reputation is earned from download volume over time.)"
              echo
              echo "**Prefer no warning at all?** Install from the wheels above instead — nothing"
              echo "is downloaded as an application, so nothing objects. Needs a terminal and"
              echo "Python 3.11+."
              echo
              echo "Full explanation, including how to check what you downloaded:"
              echo "<https://github.com/${{ github.repository }}/blob/main/docs/desktop-install.md>"
              echo
              echo "**macOS** — the first open is refused. Open **System Settings → Privacy &"
              echo "Security**, scroll to the message about \`keel\`, and choose **Open Anyway**."
              echo "You will only do this once."
              echo
              echo "**Windows** — SmartScreen shows \"Windows protected your PC\". Choose **More"
              echo "info → Run anyway**."
              echo
              echo "**Verify what you downloaded before you run it.** Every artifact carries a"
              echo "GitHub build attestation binding it to this repository, this workflow and this"
              echo "commit — which is the question a code-signing certificate answers too:"
              echo
              echo "    gh attestation verify <file> --repo ${{ github.repository }}"
              echo
              echo "\`SHA256SUMS.txt\` is attached as well. If either check fails, do not run it."
              echo
              echo "The app opens keel in your browser; there is no terminal involved. Your"
              echo "config, database and credentials live in your user Application Support /"
              echo "LocalAppData folder and are never touched by an update."
              echo
            fi
            echo "$GENERATED"
          } > /tmp/release-notes.md
          echo "composed $(wc -l < /tmp/release-notes.md) lines of notes"

      - name: Publish the release
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          # dist/* = every workspace wheel; config.yaml = the confirm-mode production config.
          gh release create "v${{ inputs.version }}" dist/* config.yaml \
            --title "keel v${{ inputs.version }}" \
            --notes-file /tmp/release-notes.md
          echo "published v${{ inputs.version }}"

  # -- desktop artifacts -------------------------------------------------------------------------
  #
  # Runs AFTER `release`, so the tag it checks out is the one that job created and published.
  #
  # THESE ARTIFACTS ARE NOT CODE-SIGNED, AND THAT IS A DECISION RATHER THAN AN OVERSIGHT.
  #
  # NEITHER PLATFORM IS SIGNED, and both are decisions with the same cause.
  #
  # macOS: notarisation requires a Developer ID certificate, which requires the $99/yr Developer
  # Program. There is no free path -- a free Apple account signs only for local development, and a
  # self-signed certificate buys nothing because Gatekeeper trusts Apple-issued Developer IDs and
  # nothing else.
  #
  # Windows: Azure Trusted Signing is ~$120/yr, MORE than Apple's, and it does not even buy the
  # same thing. Since 2024 an EV certificate no longer grants an instant SmartScreen pass;
  # reputation accrues from download volume over time, so a new certificate on a young project
  # leaves the warning in place for a while regardless. Paying more to still be warned about is
  # the worst of the three options.
  #
  # keel is open source on a small budget and has chosen not to pay either.
  #
  # What that costs the user is real and is documented rather than hidden: a `.dmg` downloaded
  # from the internet carries a quarantine flag, so macOS refuses the first open until they go to
  # System Settings -> Privacy & Security -> Open Anyway. Windows SmartScreen warns similarly.
  #
  # What replaces OS-level trust here is PROVENANCE, which is free and is arguably the more
  # honest answer for an auditable project anyway: every artifact carries a GitHub build
  # attestation tying it to this workflow, this repository and this commit, verifiable with
  #
  #     gh attestation verify <file> --repo CodeGateSoftware/keel
  #
  # plus a SHA256SUMS file in the release. That does not stop Gatekeeper -- nothing free does --
  # but it does answer "did this binary come from that source", which a signature from a $99
  # certificate answers no better.
  #
  # The publish option is spelled `publish-unsigned` deliberately: it cannot be selected without
  # reading the word, and the default is `build`, which attaches nothing to a release.
  desktop:
    needs: release
    if: ${{ inputs.desktop != 'skip' }}
    timeout-minutes: 45
    permissions:
      contents: write # attach the artifacts to the release
      id-token: write # OIDC token for the build attestation
      attestations: write # write the attestation itself
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: macos-14
            arch: arm64
          # Two DMGs rather than a universal2 build: `lipo`-merging a bundled-CPython-plus-
          # native-extension tree is fragile in practice. Note this runner image is scheduled to
          # sunset around Aug 2027.
          - os: macos-15-intel
            arch: x86_64
          - os: windows-latest
            arch: x86_64
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v7
        with:
          ref: v${{ inputs.version }}

      - uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      - name: Install the workspace
        run: uv sync --all-packages

      # The SAME stamp the release job writes. Without it a bundle reports `[checkout]`, and
      # `keel/version.py` will not call an unstamped bundle a release -- correctly, which is why
      # the smoke below can assert on it.
      - name: Stamp build info
        shell: bash
        run: |
          set -euo pipefail
          COMMIT="$(git rev-parse --short=12 HEAD)"
          cat > keel/_build_info.py <<EOF
          """Generated by .github/workflows/release.yml. Do not edit or commit."""

          VERSION = "${{ inputs.version }}"
          COMMIT = "$COMMIT"
          DIRTY = False
          EOF
          echo "stamped $COMMIT"

      - name: Freeze
        run: uv run --with pyinstaller pyinstaller packaging/keel.spec --noconfirm

      # THE STEP THAT EARNS ITS KEEP. Three of the four ways a bundle breaks are SILENT: it
      # starts cleanly, and it has no venues, or no version identity, or no templates. Every
      # assertion here corresponds to one of those, found by building a bundle and running it.
      - name: Smoke the bundle
        shell: bash
        run: |
          set -euo pipefail
          BIN="dist/keel/keel"
          [ "${{ runner.os }}" = "Windows" ] && BIN="dist/keel/keel.exe"

          OUT="$("$BIN" --version)"
          echo "$OUT"
          printf '%s' "$OUT" | grep -q "${{ inputs.version }}" || {
            echo "::error::the bundle does not report the released version"; exit 1; }
          printf '%s' "$OUT" | grep -q "release" || {
            echo "::error::the bundle is not stamped as a release build"; exit 1; }
          printf '%s' "$OUT" | grep -q "DIRTY" && {
            echo "::error::the bundle reports a dirty tree"; exit 1; } || true

          # Without collected metadata this answers "no keel distributions installed" -- the
          # deploy check that exists to catch a partial upgrade, reporting success by having
          # nothing to compare.
          "$BIN" versions || { echo "::error::the bundle cannot see its own distributions"; exit 1; }

          # Without the adapters as hidden imports this answers `0 adapter(s)`, and a packaged
          # keel with no venues is not a trading tool at all.
          ADAPTERS="$("$BIN" brokers list | head -1)"
          echo "$ADAPTERS"
          printf '%s' "$ADAPTERS" | grep -qE '^[1-9][0-9]* adapter' || {
            echo "::error::the bundle discovered no broker adapters"; exit 1; }
          # And the dev-only fake venue must never reach a shipped artifact: it would put a FAKE
          # VENUE in the venue list of a signed install a real person downloaded.
          "$BIN" brokers list | grep -qi 'fake' && {
            echo "::error::the dev-only fake venue is in the bundle"; exit 1; } || true

          # Without collected package data `init-config` cannot write a config, so a first run
          # cannot start at all.
          WORK="$(mktemp -d)"
          (cd "$WORK" && "$OLDPWD/$BIN" init-config >/dev/null && test -s config.yaml) || {
            echo "::error::the bundle cannot write a config from its templates"; exit 1; }
          echo "smoke passed"

      - name: Package (macOS)
        if: runner.os == 'macOS'
        run: |
          mkdir -p out
          packaging/macos_app.sh dist/keel out "${{ inputs.version }}"

      - name: Package (Windows)
        if: runner.os == 'Windows'
        shell: bash
        run: |
          # Inno Setup is the intended installer (per-user, no admin prompt, and the install-path
          # and version-decision UX #438 specifies). Until that script is written and tested on a
          # Windows runner, a zip is shipped rather than an untested installer -- an installer
          # nobody has run is a worse artifact than an archive everyone understands.
          mkdir -p out
          7z a -tzip "out/keel-${{ inputs.version }}-windows-${{ matrix.arch }}.zip" ./dist/keel/* >/dev/null
          ls -l out

      # Checksums travel WITH the artifacts, in the same release, so a user who was handed a
      # download link somewhere else has something local to compare against. FILES ONLY:
      # macOS packaging leaves the unzipped `keel.app/` and the `dmg-stage/` build directory
      # beside the .dmg in out/ -- checksumming those (`shasum ./*`) is what failed the first
      # publish-unsigned run, and a directory has no meaningful checksum anyway.
      - name: Checksums
        shell: bash
        run: |
          set -euo pipefail
          cd out
          # Per-leg name, not SHA256SUMS.txt: three matrix legs uploading one shared name
          # under --clobber would leave only the LAST leg's sums on the release, and a macOS
          # user could never verify their .dmg against Windows sums.
          CKSUM_FILE="SHA256SUMS-${{ runner.os }}-${{ matrix.arch }}.txt"
          if command -v sha256sum >/dev/null; then
            find . -maxdepth 1 -type f ! -name 'SHA256SUMS-*' -print0 | sort -z | xargs -0 sha256sum > "$CKSUM_FILE"
          else
            find . -maxdepth 1 -type f ! -name 'SHA256SUMS-*' -print0 | sort -z | xargs -0 shasum -a 256 > "$CKSUM_FILE"
          fi
          cat "$CKSUM_FILE"

      # The substitute for a code-signing certificate, and free. Ties each artifact to this
      # workflow, this repository and this commit; a user verifies with
      #   gh attestation verify <file> --repo ${{ github.repository }}
      # Subjects are named per OS because the attest action has no files-only filter: an
      # `out/*` glob would hand it the `keel.app/` directory, and a shared `*.dmg *.zip`
      # pattern would hand one of the two legs a glob that matches nothing.
      - name: Attest build provenance (macOS)
        if: runner.os == 'macOS'
        uses: actions/attest-build-provenance@v4
        with:
          subject-path: out/*.dmg
      - name: Attest build provenance (Windows)
        if: runner.os == 'Windows'
        uses: actions/attest-build-provenance@v4
        with:
          subject-path: out/*.zip

      - name: Upload the artifact
        uses: actions/upload-artifact@v7
        with:
          name: keel-${{ inputs.version }}-${{ runner.os }}-${{ matrix.arch }}
          path: out/*
          if-no-files-found: error

      - name: Attach to the release
        if: inputs.desktop == 'publish-unsigned'
        env:
          GH_TOKEN: ${{ github.token }}
        shell: bash
        run: |
          set -euo pipefail
          # `--clobber` so a re-run of one matrix leg replaces its own asset rather than failing
          # the whole publish on a name collision. FILES ONLY, same reason as Checksums:
          # `gh release upload out/*` cannot attach a directory, and the .dmg (not the
          # keel.app/ it was cut from) is the release artifact.
          gh release upload "v${{ inputs.version }}" $(find out -maxdepth 1 -type f | sort) --clobber
          echo "attached $(find out -maxdepth 1 -type f | wc -l | tr -d ' ') file(s) to v${{ inputs.version }}"