trackerkeeper 0.1.0__tar.gz

trackerkeeper-0.1.0/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls -la /home/august/Projects/ && ls -la /home/august/Projects/dough)",
+      "Bash(xargs -n1 basename)",
+      "Bash(timeout 300 bash -lc 'ruff check . >/tmp/ruff.txt 2>&1; echo \"ruff exit=$?\"; python -m trackerkeeper.bake --check >/tmp/bake.txt 2>&1; echo \"bake exit=$?\"')",
+      "Bash(timeout 400 pytest -q)",
+      "Bash(timeout 120 pytest -q tests/test_imports.py)",
+      "Bash(python -c \"import sys; print\\(sys.prefix\\)\")",
+      "Read(//usr/bin/**)",
+      "Bash(.venv/bin/python -c \"import trackerkeeper; print\\('ok', trackerkeeper.__file__\\)\")",
+      "Bash(timeout 400 .venv/bin/python -m pytest -q)",
+      "Bash(timeout 500 xvfb-run -a .venv/bin/python -m pytest -q)",
+      "Bash(timeout 500 .venv/bin/python -m pytest -q -p no:cacheprovider)",
+      "Bash(QT_QPA_PLATFORM=offscreen timeout 500 .venv/bin/python -m pytest -q)"
+    ]
+  }
+}

trackerkeeper-0.1.0/.gitattributes

@@ -0,0 +1,5 @@
+# Build anywhere: every text file checks out LF on every OS. Windows git
+# defaults (core.autocrlf=true on the GitHub runners) would otherwise convert
+# the working tree to CRLF — breaking the byte-exact `dough bake --check`
+# drift gate and any rendered shell script.
+* text=auto eol=lf

trackerkeeper-0.1.0/.github/release-checklist-template.md

@@ -0,0 +1,20 @@
+# Release ${TAG} — propagation checklist
+
+Auto-opened by `release-checklist.yml` on the `${TAG}` tag. Tick each channel as
+it propagates. See `docs/RELEASING.md`.
+
+## Automated — verify
+- [ ] **GitHub release** drafted by `release.yml` — `.deb`, AppImage + `.zsync`, sdist/wheel, `SHA256SUMS`, Sigstore attestations
+- [ ] Cross-distro **smoke tests** green (deb + AppImage self-containment)
+- [ ] **Review the draft** and click **Publish** ← the one human gate
+- [ ] **PyPI** — `pypi-publish.yml` uploaded `${V}`: https://pypi.org/project/trackerkeeper-base/${V}/
+- [ ] Provenance verifies: `gh attestation verify <asset> --repo wolfgangwarehaus/trackerkeeper`
+
+## Dormant / deferred — light up when configured (docs/TODO.md)
+- [ ] **AUR** — `aur.yml` pushed `trackerkeeper ${V}` (needs `AUR_SSH_PRIVATE_KEY` + AUR registration)
+- [ ] **winget / MSIX / Windows Inno** — deferred (no Windows channel yet)
+- [ ] **macOS cask** — deferred (needs an Apple Developer account)
+
+## Housekeeping
+- [ ] `docs/CHANGELOG.md`: the `[${V}]` section is dated + accurate
+- [ ] `[Unreleased]` reset to empty for the next cycle

trackerkeeper-0.1.0/.github/workflows/aur.yml

@@ -0,0 +1,48 @@
+name: aur
+
+# Publish the PKGBUILD to the AUR when a release is PUBLISHED: stamp pkgver from
+# the tag, refresh the checksum via updpkgsums, regenerate .SRCINFO, and push to
+# aur@aur.archlinux.org.
+#
+# DORMANT until BOTH: (a) the AUR reopens new-package registration (frozen after
+# the 2026 malware wave) AND (b) you add the AUR_SSH_PRIVATE_KEY secret (a
+# dedicated AUR deploy keypair; public half on your AUR account). Until then the
+# steps skip with a one-line pointer. See docs/RELEASING.md.
+
+on:
+  release:
+    types: [released]
+
+permissions:
+  contents: read
+
+jobs:
+  aur:
+    runs-on: ubuntu-latest
+    env:
+      HAVE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY != '' }}
+    steps:
+      - uses: actions/checkout@v4
+        if: env.HAVE_KEY == 'true'
+      - name: Stamp PKGBUILD pkgver from the tag
+        if: env.HAVE_KEY == 'true'
+        run: |
+          V="${{ github.event.release.tag_name }}"; V="${V#v}"
+          sed -i -E "s/^pkgver=.*/pkgver=${V}/; s/^pkgrel=.*/pkgrel=1/" packaging/aur/PKGBUILD
+      - name: Publish to the AUR
+        if: env.HAVE_KEY == 'true'
+        uses: KSXGitHub/github-actions-deploy-aur@084b0d9b15415bf9cdb65d44dad1efe37a354050 # v4.2.0
+        with:
+          pkgname: trackerkeeper
+          pkgbuild: packaging/aur/PKGBUILD
+          commit_username: wolfgangwarehaus
+          commit_email: augustvontrips@gmail.com
+          ssh_private_key: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+          commit_message: trackerkeeper ${{ github.event.release.tag_name }}
+          updpkgsums: true
+          ssh_keyscan_types: rsa,ecdsa,ed25519
+      - name: Dormant — AUR_SSH_PRIVATE_KEY not set
+        if: env.HAVE_KEY != 'true'
+        run: |
+          echo "AUR_SSH_PRIVATE_KEY is not set → AUR auto-deploy is DORMANT (no-op)."
+          echo "(AUR new-package registration is also frozen.) See docs/RELEASING.md."

trackerkeeper-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,85 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint-and-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The editable install runs setuptools-scm, which derives the version
+          # from the tag — it needs the full history + tags, not a shallow clone.
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # PySide6's offscreen platform plugin still needs the EGL/GL/xkb libs.
+      - name: System libs for headless Qt
+        run: sudo apt-get update && sudo apt-get install -y libegl1 libgl1 libxkbcommon0
+      # Install the project itself, not a hand-picked dep list — the boot smoke
+      # imports the real app, so it needs whatever [project].dependencies says
+      # (a fork that adds deps stays green without touching this file).
+      - name: Install
+        run: pip install ruff -e .
+      - name: Lint
+        run: ruff check trackerkeeper/
+      # The rig owns the smoke (one source — the same verb a maker or an AI
+      # runs locally): offscreen boot + settings dialog. See trackerkeeper/rig.py.
+      - name: Boot smoke (offscreen)
+        run: python -m trackerkeeper.rig boot
+
+  tests:
+    # Every platform trackerkeeper claims to deliver to gets the suite run ON it — the
+    # rigging-and-testing direction: a Windows/macOS code bump should fail HERE,
+    # not at release time. Linux stays the canonical leg (it also gates bake).
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The editable install runs setuptools-scm, which derives the version
+          # from the tag — it needs the full history + tags, not a shallow clone.
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # PySide6's offscreen platform plugin still needs the EGL/GL/xkb libs.
+      - name: System libs for headless Qt
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y libegl1 libgl1 libxkbcommon0
+      - name: Install (core + dev extras)
+        run: pip install -e .[dev]
+      - name: Packaging drift gate (trackerkeeper bake --check)
+        # Linux-only: the gate validates exec bits on rendered .sh, which have
+        # no meaning on the Windows filesystem.
+        if: runner.os == 'Linux'
+        run: python -m trackerkeeper.bake --check
+      - name: Pytest (offscreen)
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: pytest
+
+  # Gate-test the PyPI build itself (the publish workflow runs the same steps on a
+  # tag): catch a broken sdist/wheel or bad metadata BEFORE a release, not during.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm derives the version from the tag — needs full history.
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build + check sdist & wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*

trackerkeeper-0.1.0/.github/workflows/macos.yml

@@ -0,0 +1,224 @@
+name: macos
+
+# Build, sign, notarize, and ship the macOS .dmg + bump the Homebrew cask when a
+# release is PUBLISHED. DORMANT until the Apple secrets exist (the whole job
+# skips) — macOS is a present-but-dormant goal (docs/BAKING.md §5).
+#
+# One UNIVERSAL2 .dmg (arm64 + x86_64 in a single bundle) — trackerkeeper has no native
+# deps, so a single fat build reaches both chips (see the freeze step for the
+# per-arch-matrix fallback).
+#
+# Activate (one-time): a $99/yr Apple Developer membership, then add the secrets
+# MACOS_CERTIFICATE (base64 of a Developer ID Application .p12), MACOS_CERTIFICATE_PWD,
+# MACOS_KEYCHAIN_PWD, APPLE_TEAM_ID, and HOMEBREW_TAP_TOKEN (a PAT for the separate
+# homebrew-<tap> repo). For NOTARIZATION add EITHER the App Store Connect API key
+# (PREFERRED — scoped + revocable, no 2FA coupling): APPLE_API_KEY_ID,
+# APPLE_API_ISSUER, APPLE_API_KEY_B64 (base64 of the AuthKey_XXXX.p8); OR the
+# Apple-ID fallback: APPLE_ID + APPLE_APP_SPECIFIC_PASSWORD. See docs/RELEASING.md.
+
+on:
+  release:
+    types: [released]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to build (e.g. v0.1.0)"
+        required: true
+
+permissions:
+  contents: write # gh release upload
+
+jobs:
+  macos:
+    # macos-14 = the oldest FREE Apple-silicon image, and setup-python installs a
+    # universal2 CPython framework on it — so the freeze can emit both slices for
+    # a single universal2 .app/.dmg. The bundle's honest macOS floor is pinned to
+    # this runner's OS (see the freeze step). FALLBACK: a fork that later adds a
+    # native dependency WITHOUT universal2 wheels must switch to a per-arch
+    # (arm64 + x86_64) matrix — PyInstaller --target-arch universal2 aborts on the
+    # thin binaries (jellytoast ships exactly that matrix for its libmpv build).
+    runs-on: macos-14
+    env:
+      HAVE_APPLE: ${{ secrets.APPLE_TEAM_ID != '' }}
+      # secrets.* is NOT a valid context inside `if:` — referencing it there makes
+      # GitHub reject the whole workflow file at parse time (a 0s "workflow file
+      # issue" failure on every push). Gate via env, same as HAVE_APPLE.
+      HAVE_TAP: ${{ secrets.HOMEBREW_TAP_TOKEN != '' }}
+    permissions:
+      contents: write # gh release upload (+ attest reads the artifact)
+      id-token: write # Sigstore OIDC for build provenance
+      attestations: write # write the provenance attestation
+    steps:
+      - name: Dormant — Apple secrets not set
+        if: env.HAVE_APPLE != 'true'
+        run: |
+          echo "APPLE_TEAM_ID is not set → the macOS channel is DORMANT (no-op)."
+          echo "Activate with an Apple Developer account + the secrets. See docs/RELEASING.md."
+
+      - uses: actions/checkout@v4
+        if: env.HAVE_APPLE == 'true'
+        with:
+          ref: ${{ github.event.release.tag_name || inputs.tag }}
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        if: env.HAVE_APPLE == 'true'
+        with:
+          # setup-python's macOS builds are universal2 framework builds — needed
+          # so PyInstaller can freeze a universal2 (arm64 + x86_64) bundle.
+          python-version: "3.12"
+      - name: Resolve version
+        id: ver
+        if: env.HAVE_APPLE == 'true'
+        run: |
+          V="${{ github.event.release.tag_name || inputs.tag }}"
+          echo "version=${V#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Build the .app (render manifests + freeze)
+        if: env.HAVE_APPLE == 'true'
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[bake]" pyinstaller
+          brew install librsvg create-dmg
+          python -m trackerkeeper.bake --packaging packaging --release-version "$VERSION" --release-date "$(date -u +%F)"
+          # Render the .icns from the brand SVG (an .iconset of the required sizes).
+          ICONSET=packaging/macos/trackerkeeper.iconset
+          mkdir -p "$ICONSET"
+          # Canonical iconutil sizes only (NOT 64 — iconutil rejects a non-standard
+          # icon_64x64). Each base size + its @2x.
+          for s in 16 32 128 256 512; do
+            rsvg-convert -w "$s"     -h "$s"     trackerkeeper/assets/trackerkeeper.svg -o "$ICONSET/icon_${s}x${s}.png"
+            rsvg-convert -w $((s*2)) -h $((s*2)) trackerkeeper/assets/trackerkeeper.svg -o "$ICONSET/icon_${s}x${s}@2x.png"
+          done
+          iconutil -c icns "$ICONSET" -o packaging/macos/trackerkeeper.icns
+          # UNIVERSAL2: the spec's EXE carries target_arch="universal2" (rendered
+          # by `trackerkeeper bake`), and the universal2 CPython above lets the freeze emit
+          # both slices; trackerkeeper has no native deps, so every wheel ships universal2
+          # and the freeze never hits a thin binary.
+          #
+          # HONEST FLOOR: the bundle's REAL macOS minimum is the runner OS — this is
+          # the only macOS we ever build + smoke-test on, so we can't truthfully
+          # claim to support anything older. Match the C-extension deployment target
+          # to that floor BEFORE the freeze (so any source-built wheel agrees), then
+          # stamp it into the frozen Info.plist AFTER the freeze. An unpinned build
+          # would inherit the spec's low default and dock-bounce-and-die (dyld/Qt
+          # bail before first paint) on a too-old macOS; the offscreen smoke-test
+          # below runs ON this floor, so a too-high floor can't ship silently either.
+          FLOOR="$(sw_vers -productVersion | cut -d. -f1).0"
+          export MACOSX_DEPLOYMENT_TARGET="$FLOOR"
+          pyinstaller packaging/pyinstaller/trackerkeeper.spec --noconfirm
+          /usr/libexec/PlistBuddy -c "Set :LSMinimumSystemVersion $FLOOR" \
+            "dist/trackerkeeper.app/Contents/Info.plist"
+          echo "LSMinimumSystemVersion now: $(/usr/libexec/PlistBuddy -c \
+            'Print :LSMinimumSystemVersion' dist/trackerkeeper.app/Contents/Info.plist)"
+
+      - name: Smoke-test the .app (boots headless, offscreen)
+        if: env.HAVE_APPLE == 'true'
+        # Boot the frozen binary with no display: an import/loader failure (a
+        # missing bundled lib, a broken universal2 slice) dies fast with a real
+        # exit code; surviving ~12s means Qt + the bundle initialized. Runs ON the
+        # pinned floor OS, so a false/too-high floor can't ship silently.
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: |
+          BIN="dist/trackerkeeper.app/Contents/MacOS/trackerkeeper"
+          test -x "$BIN"
+          "$BIN" &
+          PID=$!
+          sleep 12
+          if kill -0 "$PID" 2>/dev/null; then
+            echo "still alive after 12s — Qt + bundle initialized OK"
+            kill "$PID" 2>/dev/null || true
+          else
+            wait "$PID"; rc=$?
+            echo "app exited early (rc=$rc) — likely an import/loader failure"
+            exit 1
+          fi
+
+      - name: Import the signing certificate
+        if: env.HAVE_APPLE == 'true'
+        env:
+          MACOS_CERTIFICATE: ${{ secrets.MACOS_CERTIFICATE }}
+          MACOS_CERTIFICATE_PWD: ${{ secrets.MACOS_CERTIFICATE_PWD }}
+          MACOS_KEYCHAIN_PWD: ${{ secrets.MACOS_KEYCHAIN_PWD }}
+        run: |
+          echo "$MACOS_CERTIFICATE" | base64 --decode > cert.p12
+          security create-keychain -p "$MACOS_KEYCHAIN_PWD" build.keychain
+          security default-keychain -s build.keychain
+          security unlock-keychain -p "$MACOS_KEYCHAIN_PWD" build.keychain
+          security import cert.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_KEYCHAIN_PWD" build.keychain
+          # codesign searches the keychain SEARCH LIST, not just the default — add ours.
+          security list-keychains -d user -s build.keychain $(security list-keychains -d user | tr -d '"')
+          rm -f cert.p12
+
+      - name: Sign, package, notarize, staple
+        if: env.HAVE_APPLE == 'true'
+        env:
+          # Notarization credentials — API key PREFERRED, Apple ID as fallback.
+          APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
+          APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
+          APPLE_API_KEY_B64: ${{ secrets.APPLE_API_KEY_B64 }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          IDENTITY="Developer ID Application"
+          APP="dist/trackerkeeper.app"
+          ENTITLEMENTS="packaging/macos/entitlements.plist"
+          # Sign EVERY nested Mach-O bottom-up — dylibs, .so, AND the Qt/Python
+          # .framework binaries (which are neither *.dylib nor *.so, so a name
+          # filter misses them and notarization rejects the unsigned code) — then
+          # the .app, all with the hardened runtime + entitlements (so PySide6's
+          # dylibs still load under disabled library-validation).
+          find "$APP" -type f -print0 | while IFS= read -r -d '' f; do
+            if file "$f" | grep -q "Mach-O"; then
+              codesign --force --timestamp --options runtime \
+                --entitlements "$ENTITLEMENTS" --sign "$IDENTITY" "$f"
+            fi
+          done
+          codesign --force --timestamp --options runtime \
+            --entitlements "$ENTITLEMENTS" --sign "$IDENTITY" "$APP"
+          codesign --verify --strict --verbose=2 "$APP"
+          DMG="dist/trackerkeeper-${VERSION}-macos.dmg"
+          create-dmg --volname "trackerkeeper ${VERSION}" --app-drop-link 480 120 \
+            --icon "trackerkeeper.app" 160 120 --window-size 640 280 "$DMG" "$APP"
+          codesign --force --timestamp --sign "$IDENTITY" "$DMG"
+          # Notarize the .dmg. PREFER the App Store Connect API key (scoped,
+          # individually revocable, not coupled to an Apple ID's 2FA) when its
+          # secrets exist; otherwise use the Apple ID + app-specific password.
+          if [ -n "${APPLE_API_KEY_ID:-}" ]; then
+            KEY="$(mktemp /tmp/AuthKey_XXXXXX.p8)"
+            echo "$APPLE_API_KEY_B64" | base64 --decode > "$KEY"
+            xcrun notarytool submit "$DMG" \
+              --key "$KEY" --key-id "$APPLE_API_KEY_ID" --issuer "$APPLE_API_ISSUER" --wait
+            rm -f "$KEY"
+          else
+            xcrun notarytool submit "$DMG" --apple-id "$APPLE_ID" \
+              --password "$APPLE_APP_SPECIFIC_PASSWORD" --team-id "$APPLE_TEAM_ID" --wait
+          fi
+          xcrun stapler staple "$DMG"
+
+      - name: Upload the .dmg to the release
+        if: env.HAVE_APPLE == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.event.release.tag_name || inputs.tag }}
+        run: gh release upload "$TAG" --repo "${{ github.repository }}" --clobber dist/*-macos.dmg
+
+      - name: Attest .dmg build provenance
+        if: env.HAVE_APPLE == 'true'
+        uses: actions/attest-build-provenance@v4
+        with:
+          subject-path: dist/*-macos.dmg
+
+      - name: Bump the Homebrew cask
+        if: ${{ env.HAVE_APPLE == 'true' && env.HAVE_TAP == 'true' }}
+        uses: macauley/action-homebrew-bump-cask@v1
+        with:
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          tap: wolfgangwarehaus/homebrew-tap
+          cask: trackerkeeper
+          tag: ${{ github.event.release.tag_name || inputs.tag }}

trackerkeeper-0.1.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+# Publishes the sdist + wheel to PyPI via **Trusted Publishing (OIDC)** — there is
+# NO API token to store or rotate; PyPI verifies this workflow's identity directly.
+#
+# Triggers:
+#   - release: published  → auto-publishes when a GitHub release goes public.
+#   - workflow_dispatch    → manual, for a given tag (backfill / re-run).
+#
+# One-time PyPI setup — create a pending publisher (the project doesn't exist on
+# PyPI yet, so use the "pending publisher" form):
+#   https://pypi.org/manage/account/publishing/  → Add a new pending publisher:
+#     PyPI Project Name: trackerkeeper-base
+#     Owner:             wolfgangwarehaus
+#     Repository name:   trackerkeeper
+#     Workflow name:     pypi-publish.yml
+#     Environment name:  pypi
+#   These must match the values below exactly or PyPI rejects the OIDC token.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to build + publish (e.g. v0.1.0)"
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/trackerkeeper-base/
+    permissions:
+      contents: read # gh release download
+      id-token: write # mint the short-lived OIDC token Trusted Publishing needs
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # Publish the SAME sdist + wheel bytes that release.yml built, attached to
+      # the release, and attested — don't rebuild (a second build wouldn't match
+      # the release page / SHA256SUMS / provenance). BAKING.md §6.1: Phase-2
+      # channels DOWNLOAD the published asset.
+      - name: Download the sdist + wheel from the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.event.release.tag_name || inputs.tag }}
+        run: |
+          mkdir -p dist
+          gh release download "$TAG" --repo "${{ github.repository }}" \
+            --pattern '*.whl' --pattern '*.tar.gz' --dir dist
+          python -m pip install --upgrade pip twine
+          python -m twine check dist/*
+      - name: Publish to PyPI (Trusted Publishing / OIDC)
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1 (2026-07 tip)
+        with:
+          # Idempotent: a re-run won't fail on an already-uploaded version.
+          skip-existing: true

trackerkeeper-0.1.0/.github/workflows/release-checklist.yml

@@ -0,0 +1,33 @@
+name: release-checklist
+
+# On a v* tag push, open a per-release propagation checklist issue from
+# .github/release-checklist-template.md — a durable board for tracking each
+# channel as it propagates. See docs/RELEASING.md.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  checklist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Open the propagation checklist issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          export V="${TAG#v}"
+          # Only substitute V + TAG — leave every other $-token in the template alone.
+          envsubst '${V} ${TAG}' < .github/release-checklist-template.md > /tmp/body.md
+          TITLE="Release ${TAG} — propagation checklist"
+          # Fall back without the 'release' label if it doesn't exist yet, so the
+          # issue is always created.
+          gh issue create --repo "$REPO" --title "$TITLE" --body-file /tmp/body.md --label release \
+            || gh issue create --repo "$REPO" --title "$TITLE" --body-file /tmp/body.md