Skip to content

Self-improving AI Employees for everyone

ci(workflows): align with production-CLI patterns (gh/stripe/uv/prefect)

trohitgb507b1c81741
diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.yml
index bae2b27b..562e047f 100644
--- a/.github/actions/setup/action.yml
+++ b/.github/actions/setup/action.yml
@@ -1,12 +1,16 @@
# Composite action for shared environment setup across all workflows.
# Eliminates duplicated Node/Python/uv setup.
#
+# Python version comes from the repo-root ``.python-version`` file
+# (single source of truth, also honoured by uv / pyenv / asdf). To
+# bump Python, change that file -- the composite action picks it up
+# automatically.
+#
# Usage:
# - uses: ./.github/actions/setup
# - uses: ./.github/actions/setup
# with:
-# node-version: '22'
-# python-version: '3.11'
+# node-version: '20' # override Node only; Python tracks .python-version
name: 'Setup MachinaOS Environment'
description: 'Setup Node.js, Python, and uv for cross-platform builds.'
@@ -15,29 +19,36 @@ inputs:
node-version:
description: 'Node.js version'
default: '22'
- python-version:
- description: 'Python version'
- default: '3.12'
runs:
using: composite
steps:
+ # Action versions are pinned to commit SHAs per the supply-chain
+ # hardening pass (see docs-internal/ci_cd.md). Dependabot updates
+ # these via the github-actions ecosystem group in dependabot.yml;
+ # zizmor (.github/workflows/check-zizmor.yml) enforces SHA pinning
+ # on every PR to prevent regression.
- name: Setup pnpm
- uses: pnpm/action-setup@v4
+ uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4
- name: Setup Node.js
- uses: actions/setup-node@v4
+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version: ${{ inputs.node-version }}
cache: 'pnpm'
- name: Setup Python
- uses: actions/setup-python@v5
+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
- python-version: ${{ inputs.python-version }}
+ # Sourced from repo-root .python-version (https://docs.astral.sh/uv/concepts/python-versions/#requesting-a-version).
+ # Single literal lives in that file; bump there and CI follows.
+ python-version-file: .python-version
+ # setup-uv v8 — the canonical uv installer (pdm, prefect, uv itself
+ # all use it). Replaces the older "pip install uv" pattern; v8
+ # adds automatic UV_CACHE_DIR setup + lockfile caching.
- name: Install uv
- uses: astral-sh/setup-uv@v4
+ uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
# The supervisor CLI lives at <repo>/cli/ and is invoked by pnpm
# scripts as `python -m cli ...` from the runner's system Python.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 00000000..372996bd
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,85 @@
+# Dependabot — weekly grouped dependency updates.
+#
+# Three ecosystems mirror the repo's actual dependency surface:
+# - npm: root package.json + pnpm workspace members
+# (client, server/nodejs). Dependabot v2 follows
+# pnpm workspaces from the root manifest.
+# - pip: machinaos-cli at the repo root and machinaos-server
+# under server/. Listed separately because they're
+# independent uv projects with their own pyproject.toml
+# and uv.lock (see Phase 1 of the CLI refactor —
+# the CLI is intentionally NOT in the server's uv
+# workspace).
+# - github-actions: pinned commit SHAs in every workflow + the
+# composite action; Dependabot rewrites the SHA
+# and the trailing version comment together.
+#
+# Groups keep the PR firehose manageable: one weekly PR per
+# (ecosystem, dependency-type) instead of per-package noise.
+# Reference: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+#
+# Anti-spam: open-pull-requests-limit caps each ecosystem so a single
+# burst (e.g. a major React release rippling through devDeps) can't
+# flood the review queue. The cap is per ecosystem; total ceiling is
+# 5 ecosystems x 10 = 50 open Dependabot PRs at any time.
+
+version: 2
+
+updates:
+ # ---- npm (workspace root + pnpm members) -------------------------------
+ - package-ecosystem: "npm"
+ directory: "/"
+ schedule:
+ interval: "weekly"
+ day: "monday"
+ time: "06:00"
+ timezone: "UTC"
+ open-pull-requests-limit: 10
+ versioning-strategy: "increase-if-necessary"
+ groups:
+ npm-dev-deps:
+ dependency-type: "development"
+ update-types: ["minor", "patch"]
+ npm-prod-deps:
+ dependency-type: "production"
+ update-types: ["minor", "patch"]
+ # Major bumps stay ungrouped so the diff is reviewed in isolation.
+
+ # ---- pip: machinaos-cli (repo root pyproject.toml) ---------------------
+ - package-ecosystem: "pip"
+ directory: "/"
+ schedule:
+ interval: "weekly"
+ day: "monday"
+ time: "06:00"
+ timezone: "UTC"
+ open-pull-requests-limit: 10
+ groups:
+ cli-deps:
+ update-types: ["minor", "patch"]
+
+ # ---- pip: machinaos-server (server/pyproject.toml) ---------------------
+ - package-ecosystem: "pip"
+ directory: "/server"
+ schedule:
+ interval: "weekly"
+ day: "monday"
+ time: "06:00"
+ timezone: "UTC"
+ open-pull-requests-limit: 10
+ groups:
+ server-deps:
+ update-types: ["minor", "patch"]
+
+ # ---- GitHub Actions ----------------------------------------------------
+ - package-ecosystem: "github-actions"
+ directory: "/"
+ schedule:
+ interval: "weekly"
+ day: "monday"
+ time: "06:00"
+ timezone: "UTC"
+ open-pull-requests-limit: 5
+ groups:
+ action-updates:
+ update-types: ["minor", "patch", "major"]
diff --git a/.github/workflows/check-zizmor.yml b/.github/workflows/check-zizmor.yml
new file mode 100644
index 00000000..624efee0
--- /dev/null
+++ b/.github/workflows/check-zizmor.yml
@@ -0,0 +1,91 @@
+# zizmor — static-analysis linter for GitHub Actions workflows.
+#
+# Catches:
+# - Over-granted `permissions:` (e.g., a job that doesn't need
+# `contents: write` but inherits it from the workflow default).
+# - Unpinned third-party action `uses:` (floating major-version
+# tags like `@v4` instead of pinned commit SHAs).
+# - Insecure `${{ ... }}` template expansion in `run:` blocks
+# (script-injection vectors).
+# - Reusable-workflow caller-callee permission mismatches.
+# - `pull_request_target` + checkout-of-PR-ref combinations
+# (the well-known privilege-escalation foot-gun).
+#
+# Pattern lifted from https://github.com/astral-sh/uv/blob/main/.github/workflows/check-zizmor.yml
+# Project home: https://github.com/woodruffw/zizmor
+#
+# Runs on every push/PR + weekly schedule so a regression introduced
+# between zizmor releases (their query pack expands) is caught
+# without anyone running it locally.
+
+name: Check zizmor
+
+on:
+ push:
+ branches: [main]
+ paths:
+ - '.github/workflows/**'
+ - '.github/actions/**'
+ - '.github/dependabot.yml'
+ pull_request:
+ branches: [main]
+ paths:
+ - '.github/workflows/**'
+ - '.github/actions/**'
+ - '.github/dependabot.yml'
+ schedule:
+ # Mondays 07:00 UTC — runs before the weekly Dependabot batch
+ # so action-version bumps already in flight don't trip new
+ # zizmor checks on their merge.
+ - cron: '0 7 * * 1'
+
+permissions:
+ contents: read
+
+jobs:
+ zizmor:
+ name: Lint workflows
+ runs-on: ubuntu-latest
+
+ permissions:
+ # SARIF upload to the Security tab so findings render alongside
+ # CodeQL results.
+ security-events: write
+ contents: read
+ actions: read
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+ - name: Setup Python
+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+ with:
+ python-version: '3.12'
+
+ - name: Install zizmor
+ # zizmor ships as a PyPI wheel; pip install gives us the
+ # binary on PATH without compiling Rust locally.
+ run: pip install zizmor
+
+ - name: Run zizmor
+ # --format sarif lets the Security tab ingest results.
+ # --persona auditor enables stricter checks (recommended
+ # for production CI; relaxed by default).
+ run: |
+ zizmor \
+ --format sarif \
+ --persona auditor \
+ .github/workflows/ \
+ .github/actions/ \
+ > zizmor.sarif
+ # SARIF upload happens unconditionally so findings still
+ # post even on a non-zero exit. Failing the job comes from
+ # the SARIF upload's threshold setting, not zizmor's exit.
+ continue-on-error: true
+
+ - name: Upload SARIF to Security tab
+ uses: github/codeql-action/upload-sarif@458d36d7d4f47d0dd16ca424c1d3cda0060f1360 # v3
+ with:
+ sarif_file: zizmor.sarif
+ category: zizmor
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
index 00000000..39ffd521
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,92 @@
+# CodeQL static-analysis SAST scanning.
+#
+# Two-language matrix matches MachinaOs's split: Python (CLI +
+# FastAPI backend + plugins under server/) and JavaScript/TypeScript
+# (React Flow client + Node.js sidecar at server/nodejs). One job per
+# language so a failure in one doesn't block the other's results from
+# landing in the Security tab.
+#
+# Triggers (lifted from prefect's codeql.yml + GitHub's own
+# recommended cadence):
+# - push to main: scan-then-baseline every merge
+# - pull_request: catch regressions before they land (path
+# filter excludes docs-only PRs so we don't
+# burn 15+ minutes of compute on copy edits)
+# - schedule weekly: catch zero-days in dependencies + new query-
+# pack releases without waiting for the next
+# merge. Sun 20:30 UTC matches the cadence
+# prefect uses.
+#
+# Permissions follow the least-privilege model documented at
+# https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-default-setup-for-code-scanning
+# `security-events: write` is the one required scope; everything else
+# stays at the workflow-default `none`.
+
+name: CodeQL
+
+on:
+ push:
+ branches: [main]
+ paths-ignore:
+ - 'docs-MachinaOs/**'
+ - '**/*.md'
+ pull_request:
+ branches: [main]
+ paths-ignore:
+ - 'docs-MachinaOs/**'
+ - '**/*.md'
+ schedule:
+ # Sundays 20:30 UTC. Mid-low-traffic window for runner pool +
+ # gives the Security tab a fresh baseline each week.
+ - cron: '30 20 * * 0'
+
+permissions:
+ contents: read
+
+jobs:
+ analyze:
+ name: Analyze ${{ matrix.language }}
+ runs-on: ubuntu-latest
+ timeout-minutes: 60
+
+ permissions:
+ # Minimum needed for CodeQL to publish to the Security tab.
+ # Documented at https://github.com/github/codeql-action#permissions
+ security-events: write
+ contents: read
+ actions: read
+
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - language: python
+ # Repo Python files live under cli/ + server/ + scripts/.
+ # CodeQL auto-detects entrypoints; no build step needed
+ # for Python (it's interpreted).
+ - language: javascript-typescript
+ # Combined JS/TS query pack — single language slot in
+ # the matrix per CodeQL's 2024+ convention.
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+ - name: Initialize CodeQL
+ uses: github/codeql-action/init@458d36d7d4f47d0dd16ca424c1d3cda0060f1360 # v3
+ with:
+ languages: ${{ matrix.language }}
+ # security-extended pulls in queries beyond the default
+ # security pack (e.g., taint-tracking on more sinks,
+ # CWE coverage). security-and-quality adds code-quality
+ # queries which produce noise we don't want gating PRs.
+ queries: security-extended
+
+ # No autobuild step: Python is interpreted; JS/TS via the
+ # tsgo+vite toolchain already runs in predeploy.yml — CodeQL
+ # only needs to read source files, not build artifacts.
+
+ - name: Perform CodeQL Analysis
+ uses: github/codeql-action/analyze@458d36d7d4f47d0dd16ca424c1d3cda0060f1360 # v3
+ with:
+ category: "/language:${{ matrix.language }}"
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 718a004c..d5a3bf7b 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -18,10 +18,10 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout
- uses: actions/checkout@v4
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- name: Setup Node.js
- uses: actions/setup-node@v4
+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version: '22'
diff --git a/.github/workflows/predeploy.yml b/.github/workflows/predeploy.yml
index ea5de3f6..343494fe 100644
--- a/.github/workflows/predeploy.yml
+++ b/.github/workflows/predeploy.yml
@@ -1,5 +1,22 @@
-# Reusable validation workflow called by ci.yml and release.yml
-# Jobs: build-and-lint, test-build-start
+# Reusable validation workflow called by ci.yml and release.yml.
+#
+# Job graph:
+# plan ─┬─> build-and-lint (gated on should_lint_or_test_frontend)
+# ├─> backend-tests (matrix: domain shards, gated on should_test_backend)
+# ├─> cli-tests (gated on should_test_cli)
+# ├─> test-build-start (matrix: OS, gated on should_full_build)
+# └─> ci-passed (alls-green aggregator — branch protection target)
+#
+# Patterns (Tier 3 of the CI/CD plan):
+# - `plan` job: change-detection booleans via dorny/paths-filter
+# (lifted from astral-sh/uv ci.yml). Doc-only PRs skip the heavy
+# suites; cli-only PRs skip the backend tests; etc.
+# - Domain-sharded test matrix (lifted from prefect's python-tests.yaml):
+# parallelises 1376 pytest cases by test-tree subdir so one slow
+# shard doesn't gate the others' results.
+# - `ci-passed` job using re-actors/alls-green (lifted from hatch):
+# single required-check job name for branch protection that doesn't
+# break when matrix dimensions change.
name: Predeploy
@@ -10,11 +27,86 @@ permissions:
contents: read
jobs:
+ # ----------------------------------------------------------------------
+ # plan -- change-detection booleans gate the downstream graph.
+ # ----------------------------------------------------------------------
+ plan:
+ name: Plan
+ runs-on: ubuntu-latest
+ outputs:
+ backend_changed: ${{ steps.filter.outputs.backend }}
+ frontend_changed: ${{ steps.filter.outputs.frontend }}
+ cli_changed: ${{ steps.filter.outputs.cli }}
+ workflows_changed: ${{ steps.filter.outputs.workflows }}
+ docs_only: ${{ steps.filter.outputs.docs_only }}
+ steps:
+ - name: Checkout
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+ - name: Detect changed paths
+ id: filter
+ uses: dorny/paths-filter@6852f92c20ea7fd3b0c25de3b5112db3a98da050 # v3
+ with:
+ # On `workflow_call`, paths-filter compares against the base
+ # branch automatically. For push events, it compares with the
+ # previous SHA. No `base:` needed in the workflow_call case.
+ filters: |
+ backend:
+ - 'server/**'
+ - 'pyproject.toml'
+ - 'pnpm-workspace.yaml'
+ frontend:
+ - 'client/**'
+ - 'pnpm-workspace.yaml'
+ cli:
+ - 'cli/**'
+ - 'pyproject.toml'
+ workflows:
+ - '.github/**'
+ docs_only:
+ - 'docs-MachinaOs/**'
+ - '**/*.md'
+
+ # ----------------------------------------------------------------------
+ # pre-commit -- run all pre-commit hooks on every PR. Catches missed
+ # local installs of the hook so unfixed format/lint can't land.
+ # ----------------------------------------------------------------------
+ pre-commit:
+ name: pre-commit
+ needs: plan
+ if: needs.plan.outputs.docs_only != 'true' || needs.plan.outputs.workflows_changed == 'true'
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+ - name: Setup Python
+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+ with:
+ python-version: '3.12'
+ # pre-commit caches its own hook envs under ~/.cache/pre-commit;
+ # actions/setup-python's pip cache is orthogonal -- leave at
+ # default behaviour.
+
+ - name: Run pre-commit
+ # pre-commit/action handles its own caching keyed on the
+ # pre-commit-config.yaml hash, so a hook-pin bump invalidates
+ # cleanly without manual cache busting.
+ uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+
+ # ----------------------------------------------------------------------
+ # build-and-lint -- client build + frontend tests + lint + tsgo
+ # ----------------------------------------------------------------------
build-and-lint:
+ name: Build + lint
+ needs: plan
+ # Frontend changes / workflow changes / full pushes to main always
+ # trigger this. Doc-only PRs skip.
+ if: needs.plan.outputs.docs_only != 'true'
runs-on: ubuntu-latest
steps:
- name: Checkout
- uses: actions/checkout@v4
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- name: Setup environment
uses: ./.github/actions/setup
@@ -40,32 +132,83 @@ jobs:
# bootstrap, and credentials flows to ship.
run: pnpm --filter react-flow-client run test
- - name: Backend tests (server pytest)
- # 1376 tests covering plugin contracts, credential broadcasts, native
- # LLM SDK wiring, parameter resolution, workflow ops, MCP tokens.
+ # ----------------------------------------------------------------------
+ # backend-tests -- pytest sharded by domain (prefect pattern)
+ # ----------------------------------------------------------------------
+ backend-tests:
+ name: Backend tests (${{ matrix.shard }})
+ needs: plan
+ if: needs.plan.outputs.backend_changed == 'true' || needs.plan.outputs.workflows_changed == 'true'
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ # Three shards balance parallelism vs. matrix-dispatch overhead.
+ # Add new shards by carving subdirs out of `backend-root` as
+ # the test tree grows.
+ include:
+ - shard: nodes
+ paths: tests/nodes/
+ - shard: services
+ # Pulls tests/services + tests/temporal + tests/llm +
+ # tests/credentials together because they share the same
+ # heavy setup (DI container + auth_service init).
+ paths: tests/services/ tests/temporal/ tests/llm/ tests/credentials/
+ - shard: root
+ # Root-level cross-cutting invariants (plugin self-containment,
+ # broadcast contracts, no-raw-prints, etc.). Cheap to run
+ # but logically distinct from per-domain tests.
+ paths: tests/ --ignore=tests/nodes/ --ignore=tests/services/ --ignore=tests/temporal/ --ignore=tests/llm/ --ignore=tests/credentials/
+ steps:
+ - name: Checkout
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+ - name: Setup environment
+ uses: ./.github/actions/setup
+
+ - name: Backend tests (server pytest, shard=${{ matrix.shard }})
# ``uv sync`` (no flag) includes the PEP 735 ``[dependency-groups].dev``
- # bundle by default — pytest, pytest-asyncio, pytest-mock, respx,
- # ruff. The previous ``--extra dev`` invocation read PEP 621
- # ``[project.optional-dependencies].dev``, which no longer exists
- # (moved to PEP 735 groups so ``pnpm install`` keeps dev tools
- # installed instead of stripping them on every dependency bump).
+ # bundle by default — pytest, pytest-asyncio, pytest-mock, respx, ruff.
working-directory: server
run: |
uv sync
- uv run pytest tests/ -v
+ uv run pytest ${{ matrix.paths }} -v
+
+ # ----------------------------------------------------------------------
+ # cli-tests -- supervisor CLI pytest (small, fast, separate from backend)
+ # ----------------------------------------------------------------------
+ cli-tests:
+ name: CLI tests
+ needs: plan
+ if: needs.plan.outputs.cli_changed == 'true' || needs.plan.outputs.workflows_changed == 'true'
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+ - name: Setup environment
+ uses: ./.github/actions/setup
- name: Supervisor CLI tests (pytest)
- # 106 tests covering build/start/stop pipelines, daemon, ports, docs,
- # release config, clean. Run from repo root — tests resolve workspace
- # paths via `pnpm list --json` (see cli/tests/conftest.py).
- # `pyyaml` is needed by test_release_pipeline_config.py to parse the
- # workflow files; not a CLI runtime dep, only a test-time one.
+ # 106 tests covering build/start/stop pipelines, daemon, ports,
+ # docs, release config, clean. Run from repo root — tests
+ # resolve workspace paths via `pnpm list --json`.
+ # `pyyaml` is needed by test_release_pipeline_config.py to parse
+ # the workflow files; not a CLI runtime dep, only a test-time one.
run: |
uv pip install --system pytest pytest-asyncio pyyaml
python -m pytest cli/tests/ -v
- # Test build and start from source (cross-platform)
+ # ----------------------------------------------------------------------
+ # test-build-start -- cross-OS build + start smoke test
+ # ----------------------------------------------------------------------
test-build-start:
+ name: Build + start (${{ matrix.os }})
+ needs: plan
+ # Always runs unless the change is doc-only -- catches platform-
+ # specific build regressions (Windows path handling, macOS arm
+ # binary fallbacks, etc.) that can't be ID'd from Linux alone.
+ if: needs.plan.outputs.docs_only != 'true'
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
@@ -73,7 +216,7 @@ jobs:
os: [ubuntu-latest, macos-latest, windows-latest]
steps:
- name: Checkout
- uses: actions/checkout@v4
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- name: Setup environment
uses: ./.github/actions/setup
@@ -137,3 +280,30 @@ jobs:
Receive-Job $job
exit 1
}
+
+ # ----------------------------------------------------------------------
+ # ci-passed -- single aggregator job; the one branch protection rule
+ # points at. Matrix dimensions can grow/shrink without breaking
+ # protection (hatch pattern).
+ # ----------------------------------------------------------------------
+ ci-passed:
+ name: CI passed
+ if: always()
+ needs:
+ - plan
+ - pre-commit
+ - build-and-lint
+ - backend-tests
+ - cli-tests
+ - test-build-start
+ runs-on: ubuntu-latest
+ steps:
+ - name: Check all jobs passed (or were skipped intentionally)
+ # alls-green treats `skipped` as success when listed in
+ # `allowed-skips`. Without this, a doc-only PR that skips
+ # backend-tests would fail the aggregator -- defeating the
+ # plan-job optimisation.
+ uses: re-actors/alls-green@afee1c1eac2a506084c274e9c02c8e0687b48d9e # v1.2.2
+ with:
+ allowed-skips: pre-commit, build-and-lint, backend-tests, cli-tests, test-build-start
+ jobs: ${{ toJSON(needs) }}
diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
new file mode 100644
index 00000000..0b6a468b
--- /dev/null
+++ b/.github/workflows/publish-pypi.yml
@@ -0,0 +1,148 @@
+# Reusable workflow: publish machinaos-server to PyPI via OIDC.
+#
+# Called from release.yml after the npm publish step succeeds. Uses
+# PyPI Trusted Publishing (https://docs.pypi.org/trusted-publishers/)
+# so no PYPI_TOKEN secret is needed -- the workflow's OIDC token is
+# exchanged for a short-lived publish token at PyPI's side.
+#
+# One-time admin step to enable this:
+# 1. On PyPI -> Account -> Publishing -> "Add a new pending
+# publisher", set:
+# repo: zeenie-ai/MachinaOS
+# workflow file: publish-pypi.yml
+# environment: pypi
+# 2. Push a tag to trigger the first release -- PyPI promotes the
+# pending publisher to active on first successful exchange.
+#
+# Pattern lifted from PrefectHQ/prefect + pypa/hatch. uv itself uses
+# `uv publish` directly; we prefer pypa/gh-action-pypi-publish for
+# cleaner OIDC integration + audit-tab visibility.
+
+name: Publish to PyPI
+
+on:
+ workflow_call:
+ inputs:
+ package_dir:
+ description: 'Directory containing the package to publish (relative to repo root).'
+ type: string
+ default: 'server'
+ dry_run:
+ description: 'Build the wheel but skip the upload step.'
+ type: boolean
+ default: false
+
+permissions:
+ contents: read
+
+jobs:
+ build:
+ name: Build wheel + sdist
+ runs-on: ubuntu-latest
+ outputs:
+ dist_path: ${{ steps.locate.outputs.dist_path }}
+ steps:
+ - name: Checkout
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+ - name: Setup Python
+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+ with:
+ python-version: '3.12'
+ # cache: false in release jobs (wrangler hardening) -- a
+ # poisoned pip cache would taint the wheel.
+ cache: ''
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+ - name: Build wheel + sdist
+ # `uv build` produces both wheel + sdist by default. Outputs
+ # land in `<package_dir>/dist/`. The release flow uses
+ # `--no-sources` to ensure no editable-install metadata
+ # leaks into the published artifact.
+ working-directory: ${{ inputs.package_dir }}
+ run: uv build --no-sources
+
+ - name: Locate dist directory
+ id: locate
+ run: |
+ echo "dist_path=${{ inputs.package_dir }}/dist" >> "$GITHUB_OUTPUT"
+
+ - name: Upload dist artifact
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+ with:
+ name: pypi-dist
+ path: ${{ inputs.package_dir }}/dist/
+ retention-days: 1
+
+ attest:
+ name: Generate SLSA build provenance
+ needs: build
+ runs-on: ubuntu-latest
+ permissions:
+ # OIDC token issuance for attestation signing.
+ id-token: write
+ # Required to write the attestation back to the GitHub
+ # attestations endpoint.
+ attestations: write
+ contents: read
+ steps:
+ - name: Download dist
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+ with:
+ name: pypi-dist
+ path: dist/
+
+ - name: Attest build provenance
+ # Pattern from astral-sh/uv's release workflow. Each wheel +
+ # sdist gets its own attestation in the GitHub transparency
+ # log; verifiable via `gh attestation verify`.
+ uses: actions/attest-build-provenance@96b4a1ef7235a096b17240c259729fdd70c83d45 # v2
+ with:
+ subject-path: 'dist/*'
+
+ publish:
+ name: Publish to PyPI
+ needs: [build, attest]
+ if: inputs.dry_run != true
+ runs-on: ubuntu-latest
+
+ # Environment binds the OIDC subject claim to a PyPI trusted
+ # publisher named "pypi" (configured on PyPI's side -- see
+ # docstring). PyPI rejects exchange attempts from any other env.
+ environment:
+ name: pypi
+ url: https://pypi.org/p/machinaos-server
+
+ permissions:
+ # Required for the OIDC token exchange with PyPI.
+ id-token: write
+
+ steps:
+ - name: Download dist
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+ with:
+ name: pypi-dist
+ path: dist/
+
+ - name: Publish to PyPI
+ # pypa/gh-action-pypi-publish handles the OIDC exchange + upload.
+ # `print-hash: true` writes the SHA-256 of each artifact to the
+ # job log so reviewers can cross-check what landed on PyPI
+ # against what the build job produced.
+ uses: pypa/gh-action-pypi-publish@6733eb7d741f0b11ec6a39b58540dab7590f9b7d # v1.14.0
+ with:
+ packages-dir: dist/
+ print-hash: true
+ # Skip-existing avoids a failure when a tag is re-run after
+ # PyPI already has the version (e.g. partial-success replay).
+ skip-existing: true
+
+ publish-dry-run-notice:
+ name: Dry-run notice
+ needs: build
+ if: inputs.dry_run == true
+ runs-on: ubuntu-latest
+ steps:
+ - run: echo "::notice::publish-pypi.yml dry_run=true -- PyPI upload skipped. Build + attest succeeded."
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index cfb08a61..19ec11e7 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,4 +1,20 @@
# Release workflow - predeploy gate, publish, GitHub release, then test install
+#
+# Hardening (May 2026, lifted from gh CLI / vercel / wrangler / uv):
+# - workflow_dispatch defaults to dry-run; pushes need explicit
+# dry_run=false (gemini-cli pattern; reduces accidental
+# publications from an admin clicking Run workflow).
+# - NPM_CONFIG_PROVENANCE=true via env (idiom from vercel) instead
+# of the per-command --provenance flag; survives any future
+# npm publish callsite change.
+# - SLSA build provenance attestation via actions/attest-build-
+# provenance@v2 (uv + gh CLI pattern). Renders on the GitHub
+# release as a verifiable supply-chain claim.
+# - Cache disabled in release-only setup steps (wrangler pattern)
+# to prevent a poisoned cache from previous CI runs from
+# contaminating the release tarball.
+# - pnpm audit is now BLOCKING; the old `|| true` swallowed
+# vulnerabilities.
name: Release
@@ -6,6 +22,11 @@ on:
push:
tags: ['v*.*.*']
workflow_dispatch:
+ inputs:
+ dry_run:
+ description: 'Skip the publish step (validate only).'
+ type: boolean
+ default: true
# Top-level permissions for all jobs (jobs can narrow further)
permissions:
@@ -13,6 +34,17 @@ permissions:
packages: write
id-token: write
+# `dry_run` is only meaningful on workflow_dispatch; tag-pushed
+# releases always publish. Computed once and surfaced to each
+# publish job via `if:` gates below.
+env:
+ IS_DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true }}
+ # Enables npm provenance for every `npm publish` in this workflow
+ # (https://docs.npmjs.com/generating-provenance-statements). Vercel
+ # pattern -- supersedes --provenance per-command flag so any future
+ # publish callsite picks it up automatically.
+ NPM_CONFIG_PROVENANCE: 'true'
+
jobs:
predeploy:
uses: ./.github/workflows/predeploy.yml
@@ -24,13 +56,17 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout
- uses: actions/checkout@v4
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- name: Setup environment
uses: ./.github/actions/setup
- name: Audit production dependencies
- run: pnpm audit --prod || true
+ # BLOCKING: a vulnerability in a prod dep must stop the release
+ # (previous `|| true` masked everything). To temporarily bypass,
+ # bump the audit-level threshold rather than re-introducing the
+ # silent fail.
+ run: pnpm audit --prod --audit-level moderate
# Build client once after predeploy passes, share with publish jobs
build-for-publish:
@@ -39,7 +75,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout
- uses: actions/checkout@v4
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- name: Setup environment
uses: ./.github/actions/setup
@@ -50,7 +86,7 @@ jobs:
pnpm --filter react-flow-client run build
- name: Upload built client
- uses: actions/upload-artifact@v4
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
with:
name: client-dist
path: client/dist
@@ -65,16 +101,20 @@ jobs:
id-token: write
steps:
- name: Checkout
- uses: actions/checkout@v4
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- name: Setup Node.js
- uses: actions/setup-node@v4
+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version: '22'
registry-url: 'https://registry.npmjs.org'
+ # cache: false in release jobs (wrangler hardening). A
+ # poisoned cache from previous CI runs cannot taint the
+ # tarball; release-time installs always pull fresh.
+ cache: ''
- name: Download built client
- uses: actions/download-artifact@v4
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
with:
name: client-dist
path: client/dist
@@ -83,21 +123,42 @@ jobs:
run: npm install --ignore-scripts
- name: Setup Python
- uses: actions/setup-python@v5
+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
- python-version: '3.12'
+ python-version-file: .python-version
- name: Sync versions from git tag
run: python -m cli version sync
- - name: Verify package contents
- run: npm pack --dry-run
+ - name: Verify package contents (and pack for attestation)
+ # `npm pack` (without --dry-run) writes the tarball to disk so
+ # we can attest it. The tarball name pattern is
+ # `<scoped-name-with-dash>-<version>.tgz`, e.g. `machinaos-0.0.72.tgz`.
+ run: npm pack
+
+ - name: Generate SLSA build provenance for the npm tarball
+ # Pattern from gh CLI + uv: attest-build-provenance signs the
+ # artifact via the workflow's OIDC token, publishes the
+ # attestation to GitHub's transparency log + Sigstore, and
+ # links it to the release. Verifiable via
+ # `gh attestation verify <tarball> --repo <owner>/<repo>`.
+ if: env.IS_DRY_RUN != 'true'
+ uses: actions/attest-build-provenance@96b4a1ef7235a096b17240c259729fdd70c83d45 # v2
+ with:
+ subject-path: '*.tgz'
- - name: Publish to npm with provenance
- run: npm publish --access public --provenance
+ - name: Publish to npm
+ # NPM_CONFIG_PROVENANCE env (top of workflow) enables provenance
+ # for `npm publish` -- no per-command flag needed.
+ if: env.IS_DRY_RUN != 'true'
+ run: npm publish --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+ - name: Dry-run -- skipping npm publish
+ if: env.IS_DRY_RUN == 'true'
+ run: echo "::notice::workflow_dispatch dry_run=true -- publish step skipped. Re-run with dry_run=false to publish."
+
publish-github-packages:
name: Publish to GitHub Packages
needs: build-for-publish
@@ -107,16 +168,18 @@ jobs:
packages: write
steps:
- name: Checkout
- uses: actions/checkout@v4
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- name: Setup Node.js
- uses: actions/setup-node@v4
+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version: '22'
registry-url: 'https://npm.pkg.github.com'
+ # cache: false in release jobs (wrangler hardening).
+ cache: ''
- name: Download built client
- uses: actions/download-artifact@v4
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
with:
name: client-dist
path: client/dist
@@ -125,9 +188,9 @@ jobs:
run: npm install --ignore-scripts
- name: Setup Python
- uses: actions/setup-python@v5
+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
- python-version: '3.12'
+ python-version-file: .python-version
- name: Sync versions from git tag
run: python -m cli version sync
@@ -142,20 +205,43 @@ jobs:
"
- name: Publish to GitHub Packages
+ if: env.IS_DRY_RUN != 'true'
run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ - name: Dry-run -- skipping GitHub Packages publish
+ if: env.IS_DRY_RUN == 'true'
+ run: echo "::notice::workflow_dispatch dry_run=true -- GitHub Packages publish step skipped."
+
+ # Publish machinaos-server to PyPI via OIDC trusted publishing.
+ # Runs in parallel with the npm publish jobs after the build-for-publish
+ # step succeeds. Dry-run propagates from this workflow's input.
+ publish-pypi:
+ name: Publish to PyPI
+ needs: [predeploy, audit]
+ permissions:
+ contents: read
+ id-token: write
+ attestations: write
+ uses: ./.github/workflows/publish-pypi.yml
+ with:
+ package_dir: server
+ dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true }}
+
# Create GitHub Release with auto-generated notes
create-github-release:
name: Create GitHub Release
- needs: [publish-npm, publish-github-packages]
+ needs: [publish-npm, publish-github-packages, publish-pypi]
+ # Skipped during dry-run -- there's no published release to point at
+ # and we don't want to leave stale release notes around.
+ if: needs.publish-npm.result == 'success' && github.event.inputs.dry_run != 'true'
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Checkout
- uses: actions/checkout@v4
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
with:
fetch-depth: 0
@@ -172,7 +258,9 @@ jobs:
--generate-notes \
--verify-tag
- # Test user installation after publishing
+ # Test user installation after publishing (skipped on dry-run since
+ # there's nothing newly published to install).
test-install:
needs: [create-github-release]
+ if: needs.create-github-release.result == 'success'
uses: ./.github/workflows/test-install.yml
diff --git a/.github/workflows/rollback.yml b/.github/workflows/rollback.yml
new file mode 100644
index 00000000..40c81554
--- /dev/null
+++ b/.github/workflows/rollback.yml
@@ -0,0 +1,176 @@
+# Release rollback workflow.
+#
+# Manual `workflow_dispatch`. Given a published version, marks the
+# corresponding npm tarball as deprecated with a stable message and
+# (optionally) opens a revert-the-release-commit PR so subsequent
+# CI can ship a fixed version. Pattern lifted from vercel/vercel +
+# google-gemini/gemini-cli rollback workflows.
+#
+# What this DOESN'T do (deliberate):
+# - It does not delete the npm publication. npm policy disallows
+# un-publishing public packages older than 72 hours; for fresh
+# publications, `npm unpublish` is permitted but breaks every
+# downstream consumer relying on the version. `npm deprecate`
+# is the standard rollback verb -- the install still works for
+# anyone with a lockfile, but new installs surface a warning.
+# - It does not yank from PyPI. PyPI has `pip install` shim for
+# a yank semantic but it requires manual action through the
+# PyPI admin UI -- see https://docs.pypi.org/help/#yanked.
+# - It does not delete the GitHub release. We keep the tag for
+# forensics; rollback adds a stable note to the release body.
+#
+# Inputs (only `version` is required):
+# version — semver tag to roll back, e.g. "v0.0.72"
+# deprecate_msg — message npm shows during install/list. Defaults
+# to a security-conservative template.
+# open_revert_pr — if true, also open a PR reverting the release
+# commit. Default false; usually you want to ship
+# a forward fix.
+
+name: Rollback Release
+
+on:
+ workflow_dispatch:
+ inputs:
+ version:
+ description: 'Version to roll back (e.g. v0.0.72).'
+ type: string
+ required: true
+ deprecate_msg:
+ description: 'npm deprecation notice shown to installers.'
+ type: string
+ default: 'This version has been deprecated by the maintainers. Please install the latest version.'
+ open_revert_pr:
+ description: 'Open a PR reverting the release commit.'
+ type: boolean
+ default: false
+
+permissions:
+ contents: read
+
+jobs:
+ deprecate-npm:
+ name: npm deprecate
+ runs-on: ubuntu-latest
+ # No id-token needed -- this uses NPM_TOKEN, not OIDC, because
+ # `npm deprecate` is not in the trusted-publisher allowlist.
+ permissions:
+ contents: read
+ steps:
+ - name: Checkout
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+ - name: Setup Node.js
+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+ with:
+ node-version: '22'
+ registry-url: 'https://registry.npmjs.org'
+ cache: ''
+
+ - name: Normalise version
+ id: ver
+ # `npm deprecate` wants a bare semver (e.g. 0.0.72), not a tag
+ # (e.g. v0.0.72). Strip the leading `v` if present.
+ run: |
+ v="${{ inputs.version }}"
+ v="${v#v}"
+ echo "semver=${v}" >> "$GITHUB_OUTPUT"
+
+ - name: Deprecate on npm (unscoped)
+ env:
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+ run: |
+ npm deprecate \
+ "machinaos@${{ steps.ver.outputs.semver }}" \
+ "${{ inputs.deprecate_msg }}"
+
+ - name: Deprecate on GitHub Packages (scoped)
+ env:
+ NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ npm config set @zeenie-ai:registry https://npm.pkg.github.com
+ npm deprecate \
+ "@zeenie-ai/machinaos@${{ steps.ver.outputs.semver }}" \
+ "${{ inputs.deprecate_msg }}"
+
+ yank-pypi-notice:
+ name: PyPI yank reminder
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ steps:
+ - name: Print PyPI yank instructions
+ # PyPI yank is gated on UI access -- no API path that the
+ # release token can take. Emit a notice so the operator
+ # remembers to do this by hand.
+ run: |
+ echo "::notice title=Manual PyPI yank required::Yank machinaos-server@${{ inputs.version }} via https://pypi.org/manage/project/machinaos-server/release/${{ inputs.version }}/ -- 'Options' -> 'Yank'."
+
+ open-revert-pr:
+ name: Open revert PR
+ needs: deprecate-npm
+ if: inputs.open_revert_pr == true
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ pull-requests: write
+ steps:
+ - name: Checkout
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ with:
+ fetch-depth: 0
+
+ - name: Resolve release commit
+ id: commit
+ # The release commit is the one the tag points at. `git
+ # rev-list -n1 <tag>` works regardless of whether the tag
+ # is annotated or lightweight.
+ run: |
+ sha=$(git rev-list -n1 "${{ inputs.version }}")
+ echo "sha=${sha}" >> "$GITHUB_OUTPUT"
+
+ - name: Create revert branch + commit
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ branch="rollback/${{ inputs.version }}"
+ git config user.name "github-actions[bot]"
+ git config user.email "github-actions[bot]@users.noreply.github.com"
+ git checkout -b "${branch}"
+ git revert --no-edit "${{ steps.commit.outputs.sha }}"
+ git push origin "${branch}"
+
+ gh pr create \
+ --base main \
+ --head "${branch}" \
+ --title "Revert: ${{ inputs.version }} (rollback)" \
+ --body "Automated revert of ${{ inputs.version }}.
+
+ npm package deprecated via rollback.yml.
+ PyPI yank pending manual action -- see https://pypi.org/manage/project/machinaos-server/.
+
+ Reason: ${{ inputs.deprecate_msg }}"
+
+ summary:
+ name: Rollback summary
+ needs: [deprecate-npm, yank-pypi-notice]
+ if: always()
+ runs-on: ubuntu-latest
+ steps:
+ - name: Print summary
+ run: |
+ {
+ echo "## Rollback summary for ${{ inputs.version }}"
+ echo ""
+ echo "| Step | Status |"
+ echo "|---|---|"
+ echo "| npm deprecate | ${{ needs.deprecate-npm.result }} |"
+ echo "| PyPI yank reminder | ${{ needs.yank-pypi-notice.result }} |"
+ echo "| Revert PR | ${{ inputs.open_revert_pr == true && 'requested' || 'skipped (open_revert_pr=false)' }} |"
+ echo ""
+ echo "Next steps:"
+ echo ""
+ echo "1. Manually yank \`machinaos-server@${{ inputs.version }}\` from PyPI."
+ echo "2. If shipping a forward fix, bump version and re-run release.yml."
+ echo "3. If reverting, merge the rollback PR (if requested)."
+ } >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/test-install.yml b/.github/workflows/test-install.yml
index 5a3951f0..0ba3bf68 100644
--- a/.github/workflows/test-install.yml
+++ b/.github/workflows/test-install.yml
@@ -19,20 +19,27 @@ jobs:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
steps:
+ - name: Checkout
+ # Required so .python-version is on disk for setup-python below.
+ # The actual MachinaOS install under test comes from npm / a
+ # separate git clone -- this checkout is only used to source
+ # the toolchain version file (single source of truth).
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
- name: Setup pnpm
- uses: pnpm/action-setup@v4
+ uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4
with:
version: 9
- name: Setup Node.js
- uses: actions/setup-node@v4
+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version: '22'
- name: Setup Python
- uses: actions/setup-python@v5
+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
- python-version: '3.12'
+ python-version-file: .python-version
- name: Install uv
run: pip install uv
@@ -116,20 +123,27 @@ jobs:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
steps:
+ - name: Checkout
+ # Required so .python-version is on disk for setup-python below.
+ # The actual MachinaOS install under test comes from npm / a
+ # separate git clone -- this checkout is only used to source
+ # the toolchain version file (single source of truth).
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
- name: Setup pnpm
- uses: pnpm/action-setup@v4
+ uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4
with:
version: 9
- name: Setup Node.js
- uses: actions/setup-node@v4
+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version: '22'
- name: Setup Python
- uses: actions/setup-python@v5
+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
- python-version: '3.12'
+ python-version-file: .python-version
- name: Install uv
run: pip install uv
diff --git a/.gitignore b/.gitignore
index 06776524..66abbfcb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -113,7 +113,10 @@ venv/
# uv (Python package manager)
uv.lock
server/uv.lock
-.python-version
+# .python-version at the repo root IS tracked -- it's the project-wide
+# toolchain pin (read by uv, pyenv, asdf, AND ``setup-python`` via
+# python-version-file: in our GitHub Actions workflows). Per-developer
+# overrides live in server/.python-version (still ignored).
server/.python-version
# =============================================================================
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 00000000..a40f1195
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,91 @@
+# pre-commit hooks shared across Python (ruff) + JS/TS (eslint, prettier)
+# + workflow files (actionlint).
+#
+# Install once with: pre-commit install
+# Run on all files: pre-commit run --all-files
+# Update hook pins: pre-commit autoupdate
+#
+# Hook pins are revisions, not floating tags — pre-commit caches per
+# revision, and Dependabot bumps these via the `github-actions`
+# ecosystem (pre-commit-ci.com extends Dependabot's coverage to
+# pre-commit's own rev pins via the same PR cadence).
+#
+# CI mirror: `predeploy.yml` runs `pre-commit run --all-files` so
+# unfixed lint issues block merges even when a contributor skipped
+# `pre-commit install` locally.
+
+default_install_hook_types:
+ - pre-commit
+ - commit-msg
+
+# Run hooks against staged files only by default; CI uses
+# `pre-commit run --all-files` for full-tree validation.
+default_stages: [pre-commit]
+
+repos:
+ # ---------------------------------------------------------------- stdlib
+ - repo: https://github.com/pre-commit/pre-commit-hooks
+ rev: v5.0.0
+ hooks:
+ - id: trailing-whitespace
+ exclude: '\.md$' # Markdown trailing whitespace = line break
+ - id: end-of-file-fixer
+ - id: check-yaml
+ args: ['--allow-multiple-documents']
+ - id: check-toml
+ - id: check-json
+ - id: check-merge-conflict
+ - id: check-added-large-files
+ args: ['--maxkb=500'] # generous cap; binaries should live elsewhere
+ - id: detect-private-key
+
+ # ---------------------------------------------------------------- Python: ruff
+ # Format + lint in one pass. Matches server/pyproject.toml's
+ # [tool.ruff] config (line-length=140, ignores E402/E701).
+ - repo: https://github.com/astral-sh/ruff-pre-commit
+ rev: v0.8.4
+ hooks:
+ - id: ruff-format
+ types_or: [python, pyi]
+ - id: ruff
+ args: ['--fix', '--exit-non-zero-on-fix']
+ types_or: [python, pyi]
+
+ # ---------------------------------------------------------------- JS/TS: prettier
+ # Prettier owns formatting (semicolons, quote style, indent). ESLint
+ # is invoked separately below for lint rules.
+ - repo: https://github.com/pre-commit/mirrors-prettier
+ rev: v4.0.0-alpha.8
+ hooks:
+ - id: prettier
+ # Limit to the client/ workspace -- the server's TS sidecar
+ # (server/nodejs/) is generated/copied and intentionally
+ # unprettierified to keep diffs against upstream minimal.
+ files: '^client/.*\.(ts|tsx|js|jsx|json|css|md)$'
+ additional_dependencies:
+
+ # ---------------------------------------------------------------- JS/TS: eslint
+ # Run on staged TS/TSX files only. Full workspace lint runs in
+ # predeploy.yml via `pnpm --filter react-flow-client run lint`.
+ - repo: https://github.com/pre-commit/mirrors-eslint
+ rev: v9.17.0
+ hooks:
+ - id: eslint
+ files: '^client/src/.*\.(ts|tsx)$'
+ additional_dependencies:
+ # Match the ESLint major version in client/package.json so
+ # plugin compatibility holds across the local + CI run.
+ - eslint@9
+ - typescript-eslint@8
+ - eslint-plugin-react-hooks@5
+
+ # ---------------------------------------------------------------- Workflows: actionlint
+ # Catches GitHub Actions schema errors, shellcheck issues inside
+ # `run:` blocks, and known anti-patterns (e.g. running an action
+ # without a pinned version -- complements zizmor's deeper scan).
+ - repo: https://github.com/rhysd/actionlint
+ rev: v1.7.4
+ hooks:
+ - id: actionlint
diff --git a/.python-version b/.python-version
new file mode 100644
index 00000000..e4fba218
--- /dev/null
+++ b/.python-version
@@ -0,0 +1 @@
+3.12
diff --git a/docs-internal/ci_cd.md b/docs-internal/ci_cd.md
index a20dcd18..d2c62613 100644
--- a/docs-internal/ci_cd.md
+++ b/docs-internal/ci_cd.md
@@ -1,328 +1,269 @@
# CI/CD Pipeline
-Internal reference for the GitHub Actions CI/CD pipeline. Covers all workflows, the shared composite action, predeploy validation, release publishing, and documentation deployment.
+Internal reference for MachinaOs's GitHub Actions setup. Workflow inventory, security posture, release flow.
---
-## Overview
+## Workflow inventory
```
- +------------------+
- push to main ---------> | ci.yml |---+
- PR to main -----------> | | |
- +------------------+ |
- | +--------------------+
- PR to main (Dockerfile +------------------+ +--> | predeploy.yml |
- or compose changes) --> | docker-build.yml |---+--> | (reusable) |
- +------------------+ | | |
- | | - build-and-lint |
- v*.*.* tag push ------> +------------------+ | | - docker-build |
- GitHub release -------> | release.yml |---+ | - docker-compose |
- manual dispatch ------> | | | - test-install |
- | +-- predeploy --+ +--------------------+
- | |
- | +-- publish-npm ---------> npmjs.org (machina)
- | +-- publish-github-pkgs -> GitHub Packages (@zeenie-ai/machina)
- +------------------+
+ +------------------+
+ push to main ----------> | ci.yml |---+
+ PR to main ------------> | | |
+ +------------------+ |
+ | +---------------------+
+ +--> | predeploy.yml |
+ | | (workflow_call) |
+ v*.*.* tag push -------> +------------------+ | | |
+ manual dispatch -------> | release.yml |---+ | - plan |
+ | (dry-run by | | - pre-commit |
+ | default for | | - build-and-lint |
+ | manual runs) | | - backend-tests |
+ +------------------+ | (3 shards) |
+ | | - cli-tests |
+ +-- predeploy | - test-build-start |
+ +-- audit | (3 OS) |
+ +-- build-for-publish| - ci-passed (alls) |
+ +-- publish-npm +---------------------+
+ +-- publish-github-packages
+ +-- publish-pypi --> publish-pypi.yml (reusable)
+ +-- create-github-release
+ +-- test-install --> test-install.yml
+
+ manual dispatch -------> +------------------+
+ | rollback.yml | npm deprecate + (optional) revert PR
+ +------------------+
+
+ weekly + on PR --------> +------------------+
+ | codeql.yml | Python + JS/TS SAST (security-extended)
+ +------------------+
+
+ on .github changes ----> +------------------+
+ | check-zizmor.yml| workflow-security linter (SARIF)
+ +------------------+
push to docs-MachinaOs/ +------------------+
- manual dispatch ------> | docs.yml |-------> Mintlify (docs site)
- +------------------+
+ | docs.yml | Mintlify documentation deploy
+ +------------------+
```
-### Workflow Summary
+### Workflow summary
| Workflow | File | Triggers | Purpose |
|----------|------|----------|---------|
-| CI | `.github/workflows/ci.yml` | Push to main, PRs to main | Validate every code change via predeploy |
-| Docker Build | `.github/workflows/docker-build.yml` | PRs to main (Dockerfile/compose changes) | Validate Docker-specific changes via predeploy |
-| Release | `.github/workflows/release.yml` | `v*.*.*` tags, GitHub releases, manual | Predeploy gate then publish to npm + GitHub Packages |
-| Deploy Docs | `.github/workflows/docs.yml` | Push to `docs-MachinaOs/**` on main, manual | Deploy Mintlify documentation |
-| Predeploy | `.github/workflows/predeploy.yml` | Called by other workflows (`workflow_call`) | Reusable validation: build, lint, Docker, cross-platform install |
-| Setup Action | `.github/actions/setup/action.yml` | Used as composite action step | Shared Node.js + Python + uv environment setup |
-
-### Required Secrets
-
-| Secret | Used By | Description |
+| CI | `.github/workflows/ci.yml` | push/PR → main | Delegates to predeploy.yml |
+| Predeploy | `.github/workflows/predeploy.yml` | `workflow_call` | Plan + pre-commit + build/lint + sharded tests + OS-matrix build/start + alls-green |
+| Release | `.github/workflows/release.yml` | `v*.*.*` tag, manual (dry-run default) | predeploy → audit → publish (npm + GH Packages + PyPI) → SLSA attest → release → test-install |
+| Publish PyPI | `.github/workflows/publish-pypi.yml` | `workflow_call` | OIDC trusted publishing for `machinaos-server` |
+| Test Install | `.github/workflows/test-install.yml` | manual, called from release | Cross-platform install smoke (3 OS × 3 paths) |
+| Rollback | `.github/workflows/rollback.yml` | manual (`workflow_dispatch`) | npm deprecate + optional revert PR |
+| CodeQL | `.github/workflows/codeql.yml` | push/PR + weekly Sun 20:30 UTC | Python + JS/TS SAST |
+| Zizmor | `.github/workflows/check-zizmor.yml` | `.github/**` changes + weekly Mon 07:00 UTC | Workflow-security linter |
+| Docs | `.github/workflows/docs.yml` | push to `docs-MachinaOs/**` | Mintlify deploy |
+| Setup | `.github/actions/setup/action.yml` | (composite) | pnpm 9 + Node 22 + Python (from `.python-version`) + uv |
+
+### Supply chain
+
+- **All action `uses:` references are pinned to commit SHAs.** Enforced by [zizmor](https://github.com/woodruffw/zizmor) on every PR touching `.github/`. Dependabot rewrites pins via the `github-actions` ecosystem group.
+- **`.github/dependabot.yml`** — weekly grouped updates for npm + pip (root + server/) + github-actions ecosystems. Each grouped PR is one ecosystem × one dependency-type.
+- **`.pre-commit-config.yaml`** — ruff (format + lint), prettier (client/), eslint, actionlint, stdlib hygiene. Mirrored as a CI job in predeploy.yml so missed local installs still gate merges.
+- **`.python-version`** — single source of truth (`3.12`). Consumed via `python-version-file:` in `setup-python` everywhere except the `test-install.yml` jobs which run after `actions/checkout` so the file is available.
+
+### Required secrets
+
+| Secret | Used by | Description |
|--------|---------|-------------|
-| `NPM_TOKEN` | release.yml | npm registry authentication for publishing |
-| `GITHUB_TOKEN` | release.yml | GitHub Packages authentication (auto-provided by Actions) |
-| `MINTLIFY_TOKEN` | docs.yml | Mintlify documentation deployment token |
+| `NPM_TOKEN` | release.yml, rollback.yml | npm registry publish + deprecate |
+| `GITHUB_TOKEN` | release.yml, rollback.yml | GitHub Packages publish + revert-PR creation (auto-provided) |
+| `MINTLIFY_TOKEN` | docs.yml | Mintlify documentation deployment |
----
+PyPI publishing uses **OIDC trusted publishing** (no PYPI_TOKEN secret needed). One-time setup: configure MachinaOs as a trusted publisher on PyPI with workflow=`publish-pypi.yml`, environment=`pypi`.
-## Composite Setup Action
+---
-**File:** `.github/actions/setup/action.yml`
+## Composite setup action
-Shared environment setup used by `predeploy.yml` jobs. Eliminates duplicated Node/Python/uv installation across workflows.
+**File:** [.github/actions/setup/action.yml](../.github/actions/setup/action.yml)
```yaml
-# Usage in workflow steps:
- uses: ./.github/actions/setup
- uses: ./.github/actions/setup
with:
- node-version: '22'
+ node-version: '20' # override Node only; Python tracks .python-version
```
-### What It Installs
-
-| Tool | Default Version | Action Used |
-|------|----------------|-------------|
-| Node.js | 20 | `actions/setup-node@v4` (with npm cache) |
-| Python | 3.12 | `actions/setup-python@v5` |
-| uv | latest | `astral-sh/setup-uv@v4` |
-
-### Inputs
+| Tool | Version source | Action (pinned SHA) |
+|------|---------------|---------------------|
+| pnpm | hard-coded `9` (default) | `pnpm/action-setup` |
+| Node.js | `node-version` input, default `22` | `actions/setup-node` |
+| Python | `.python-version` file (`3.12`) | `actions/setup-python` |
+| uv | latest in v8 line | `astral-sh/setup-uv` |
-| Input | Default | Description |
-|-------|---------|-------------|
-| `node-version` | `'20'` | Node.js version to install |
-| `python-version` | `'3.12'` | Python version to install |
-
-Python and uv are needed because `postinstall.js` skips Python venv setup in CI, so they must be available for the `machina build` command in `test-install`.
+After tool install, the composite installs the supervisor CLI editably (`uv pip install --system -e .`) and runs a verify step that prints each tool's version.
---
-## Predeploy Validation
-
-**File:** `.github/workflows/predeploy.yml`
-
-The core reusable workflow. Triggered via `workflow_call` by `ci.yml`, `docker-build.yml`, and `release.yml`. Contains 4 jobs -- `build-and-lint`, `docker-build`, and `test-install` run in parallel; `docker-compose-test` depends on `docker-build`.
-
-### Job: build-and-lint
-
-Validates that the full project builds and the client passes linting.
-
-| Step | Command | Description |
-|------|---------|-------------|
-| Checkout | `actions/checkout@v4` | Clone repo |
-| Setup environment | `./.github/actions/setup` | Install Node.js 20, Python 3.12, uv |
-| Build all services | `npm run build` | Full production build |
-| Lint client | `cd client && npm run lint` | ESLint/TypeScript validation |
+## Predeploy validation
-### Job: docker-build
+**File:** [.github/workflows/predeploy.yml](../.github/workflows/predeploy.yml)
-Validates all 3 Docker images build successfully. Uses Docker Buildx with GitHub Actions cache for layer reuse.
+Six jobs gated by a `plan` job that emits change-detection booleans (lifted from [astral-sh/uv's `ci.yml`](https://github.com/astral-sh/uv/blob/main/.github/workflows/ci.yml)):
-| Image | Context | Dockerfile | Notes |
-|-------|---------|------------|-------|
-| Frontend | `./client` | `./client/Dockerfile` | Multi-stage build, `target: production` |
-| Backend | `./server` | `./server/Dockerfile` | Python 3.12-slim |
-| WhatsApp | `./docker` | `./docker/Dockerfile.whatsapp` | Node.js 20-alpine with whatsapp-rpc |
+- `plan` — `dorny/paths-filter` decides which downstream jobs need to run. Boolean outputs: `backend_changed`, `frontend_changed`, `cli_changed`, `workflows_changed`, `docs_only`.
+- `pre-commit` — runs `pre-commit run --all-files`. Catches lint/format issues for contributors who haven't installed the hook locally. Skipped for doc-only PRs (unless workflows also changed).
+- `build-and-lint` — full `pnpm run build` + frontend tests (vitest, 148 cases) + ESLint + tsgo type-check. Skipped for doc-only PRs.
+- `backend-tests` — pytest sharded by domain (prefect pattern):
+ - `nodes` — `tests/nodes/`
+ - `services` — `tests/services/` + `tests/temporal/` + `tests/llm/` + `tests/credentials/`
+ - `root` — everything else (cross-cutting invariants)
-All builds use:
-- `docker/setup-buildx-action@v3`
-- `docker/build-push-action@v6`
-- `push: false` (validation only, no registry push)
-- `cache-from: type=gha` / `cache-to: type=gha,mode=max` (GitHub Actions layer cache)
+ Gated on `backend_changed || workflows_changed`. Each shard runs the same `uv sync` + `uv run pytest` pattern.
+- `cli-tests` — 106 CLI tests via `python -m pytest cli/tests/`. Gated on `cli_changed || workflows_changed`.
+- `test-build-start` — cross-OS (`ubuntu-latest`, `macos-latest`, `windows-latest`) build + start smoke. Verifies `client/dist/` + `server/.venv/` materialise and the supervisor brings up the backend reachable at `localhost:3010/health`. Skipped for doc-only PRs.
+- `ci-passed` — single aggregator job using [`re-actors/alls-green`](https://github.com/re-actors/alls-green) (hatch pattern). Branch protection targets this one job name; matrix changes don't break protection rules. `allowed-skips` lets the plan-job optimisations skip downstream jobs without failing the aggregator.
-### Job: docker-compose-test
-
-**Depends on:** `docker-build`
-
-Full-stack smoke test using the production Docker Compose configuration.
-
-**Steps:**
-1. Create `.env` from `.env.template`
-2. Build with `docker compose -f docker-compose.prod.yml build`
-3. Start services with `docker compose -f docker-compose.prod.yml up -d`
-4. Health check loop (30 retries, 2s interval = 60s max):
- - Backend: `curl -sf http://localhost:3010/health`
- - Frontend: `curl -f http://localhost:3000`
- - Print `docker compose ps` on success
-5. On failure: dump all container logs
-6. Always: `docker compose -f docker-compose.prod.yml down -v` (cleanup)
+---
-### Job: test-install
+## Release workflow
-Cross-platform npm package installation and CLI validation.
+**File:** [.github/workflows/release.yml](../.github/workflows/release.yml)
-**Matrix:**
+### Triggers
+| Trigger | Behaviour |
+|---------|-----------|
+| Push of `v*.*.*` tag | Full release (npm + GH Packages + PyPI + SLSA attest + GitHub release + test-install) |
+| `workflow_dispatch` | Dry-run by default; explicit `dry_run=false` required to publish (gemini-cli pattern) |
-| Axis | Values |
-|------|--------|
-| OS | `ubuntu-latest`, `macos-latest`, `windows-latest` |
-| Node.js | 20, 22 |
+### Job graph
-Total: **6 combinations**, `fail-fast: false` (all run regardless of individual failures).
+```
+predeploy (uses predeploy.yml)
+ |
+ v
+audit -- pnpm audit --prod --audit-level moderate (BLOCKING)
+ |
+ v
+build-for-publish -- once-per-release client build, uploaded as artifact
+ | | |
+ v v v
+publish-npm publish-github-packages publish-pypi
+ | | (uses publish-pypi.yml)
+ +- SLSA +- npm scope rewrite +- uv build --no-sources
+ +- attest-build-provenance@v2 +- attest-build-provenance@v2
+ +- conditional on dry_run +- pypa/gh-action-pypi-publish
+ +- OIDC, no token
+ | | |
+ v v v
+create-github-release -- generate-notes + verify-tag (skipped on dry-run)
+ |
+ v
+test-install (uses test-install.yml)
+```
-**Steps:**
-1. Checkout
-2. Setup environment (composite action with matrix `node-version`)
-3. `npm pack` -- create tarball
-4. `npm install -g machina-*.tgz` -- global install from tarball
-5. `machina --help` -- verify CLI is available
-6. `machina build` -- install client deps, build client, setup Python venv
-7. Verify build artifacts exist at `$(npm root -g)/machina`:
- - `.env` file
- - `client/dist/` directory
- - `server/.venv/` directory
-8. `machina start &` -- start in background, wait 10s, verify process is still running
+### Hardening (lifted from gh CLI + vercel + wrangler + uv)
-All steps use `shell: bash` for cross-platform compatibility (Windows uses Git Bash).
+- `NPM_CONFIG_PROVENANCE=true` set at workflow env-level — supersedes per-command `--provenance` flag.
+- `pnpm audit --prod --audit-level moderate` is **blocking** (previous `|| true` masked vulnerabilities).
+- `workflow_dispatch` defaults `dry_run=true`; explicit override required to publish.
+- `cache: ''` on `setup-node` in publish jobs — prevents poisoned-cache supply-chain contamination (wrangler pattern).
+- `actions/attest-build-provenance@v2` on every published artifact (npm tarball + Python wheel + sdist). SLSA Level 3. Verifiable via `gh attestation verify <artifact> --repo zeenie-ai/MachinaOS`.
---
-## CI Workflow
+## Reusable: publish-pypi.yml
-**File:** `.github/workflows/ci.yml`
+**File:** [.github/workflows/publish-pypi.yml](../.github/workflows/publish-pypi.yml)
-Thin wrapper that delegates all validation to `predeploy.yml`.
+Called via `workflow_call` from release.yml. Three jobs:
-```yaml
-on:
- push:
- branches: [main]
- pull_request:
- branches: [main]
-
-jobs:
- predeploy:
- uses: ./.github/workflows/predeploy.yml
-```
+1. `build` — `uv build --no-sources` in `server/`, produces wheel + sdist, uploads artifact.
+2. `attest` — `actions/attest-build-provenance@v2` signs each artifact via OIDC.
+3. `publish` — `pypa/gh-action-pypi-publish` with `environment: pypi` for the OIDC subject claim. `skip-existing: true` so re-runs after partial failures don't error.
-Every push to main and every PR targeting main runs the full predeploy suite (build, lint, Docker, cross-platform install).
+Inputs:
+- `package_dir` (default `server`)
+- `dry_run` (boolean) — skips the publish job
---
-## Docker Build Workflow
+## Rollback workflow
-**File:** `.github/workflows/docker-build.yml`
+**File:** [.github/workflows/rollback.yml](../.github/workflows/rollback.yml)
-Scoped validation for Docker-related changes. Only triggers when specific files are modified in a PR.
+Manual `workflow_dispatch` with inputs:
+- `version` (required, e.g. `v0.0.72`)
+- `deprecate_msg` (default: security-conservative template)
+- `open_revert_pr` (boolean, default `false`)
-```yaml
-on:
- pull_request:
- branches: [main]
- paths:
- - 'client/Dockerfile'
- - 'server/Dockerfile'
- - 'docker/Dockerfile.whatsapp'
- - 'docker-compose*.yml'
-```
+Three jobs:
+1. `deprecate-npm` — `npm deprecate` on both `machinaos@VERSION` (npm) and `@zeenie-ai/machinaos@VERSION` (GitHub Packages).
+2. `yank-pypi-notice` — prints PyPI yank instructions (PyPI yank is UI-only, no API).
+3. `open-revert-pr` — opens a `rollback/<version>` branch + revert PR (skipped unless `open_revert_pr=true`).
-Delegates to `predeploy.yml`. Dockerfile changes in PRs get validated by both `ci.yml` (always runs on PRs) and `docker-build.yml` (path-scoped). The reusable workflow pattern and GHA caching make this overlap low-cost.
+A `summary` job posts a step-summary table of what ran.
---
-## Release Workflow
-
-**File:** `.github/workflows/release.yml`
-
-Publishes the npm package after predeploy validation passes.
+## Security workflows
-### Triggers
-
-| Trigger | Condition |
-|---------|-----------|
-| Push tags | `v*.*.*` (e.g., `v1.0.0`, `v2.3.1`) |
-| Release | GitHub release published |
-| Manual | `workflow_dispatch` |
+### CodeQL
-### Job: predeploy (gate)
-
-Calls `predeploy.yml` as a prerequisite. Both publish jobs require this to pass (`needs: predeploy`).
-
-### Job: publish-npm
-
-Publishes the unscoped `machina` package to the public npm registry.
-
-```
-npm install --ignore-scripts # Install deps without running postinstall
-npm pack --dry-run # Verify package contents
-npm publish --access public # Publish to npmjs.org
-```
+**File:** [.github/workflows/codeql.yml](../.github/workflows/codeql.yml)
-Uses `NODE_AUTH_TOKEN` from `secrets.NPM_TOKEN`. Registry URL: `https://registry.npmjs.org`.
+Two-language matrix:
+- `python` — covers cli/, server/, scripts/.
+- `javascript-typescript` — covers client/, server/nodejs/.
-### Job: publish-github-packages
+Triggers: push to main + PR to main (both with `paths-ignore` excluding docs) + weekly schedule (Sun 20:30 UTC). Query pack: `security-extended` (broader than default, narrower than `security-and-quality` which adds noisy code-quality queries).
-Publishes the scoped `@zeenie-ai/machina` package to GitHub Packages.
+### Zizmor
-Requires `packages: write` permission. Before publishing, an inline Node.js script rewrites `package.json`:
+**File:** [.github/workflows/check-zizmor.yml](../.github/workflows/check-zizmor.yml)
-```javascript
-// Executed at build time to scope the package name:
-const pkg = require('./package.json');
-pkg.name = '@zeenie-ai/machina';
-pkg.publishConfig = { registry: 'https://npm.pkg.github.com' };
-require('fs').writeFileSync('package.json', JSON.stringify(pkg, null, 2));
-```
+Lints workflows for over-granted permissions, unpinned action `uses:`, insecure `${{ ... }}` template expansion, and `pull_request_target` + checkout-of-PR-ref combinations. Triggers on `.github/**` changes + weekly Mon 07:00 UTC (before the Mon 06:00 Dependabot batch).
-Then publishes via `npm publish` with `GITHUB_TOKEN` as auth token. Registry URL: `https://npm.pkg.github.com`.
+Outputs SARIF to the Security tab.
---
-## Docs Workflow
-
-**File:** `.github/workflows/docs.yml`
+## Test-install workflow
-Deploys the Mintlify documentation site when docs change.
+**File:** [.github/workflows/test-install.yml](../.github/workflows/test-install.yml)
-### Triggers
-
-| Trigger | Condition |
-|---------|-----------|
-| Push | Changes to `docs-MachinaOs/**` on main branch |
-| Manual | `workflow_dispatch` |
+Validates the end-user install paths after a release publishes (or on manual dispatch). Three jobs × three OS = nine matrix cells:
-### Steps
+| Job | What it does |
+|-----|--------------|
+| `test-npm-install` | `npm install -g machinaos`, run `machina --help` / `--version`, smoke-start the backend |
+| `test-git-clone` | `git clone` the public repo, `pnpm run build`, smoke-start |
+| `test-install-script-unix` / `test-install-script-windows` | Curl/iwr the install script from the repo, validate the resulting `machina` is on PATH |
-1. Checkout repo
-2. Setup Node.js 20
-3. `npm install -g mintlify` -- install Mintlify CLI
-4. `mintlify deploy` -- deploy docs (working directory: `docs-MachinaOs`)
-
-Uses `MINTLIFY_TOKEN` secret for authentication.
+Each job runs an `actions/checkout` first so `.python-version` is available for `setup-python` — independent of the install path being tested.
---
-## Workflow Dependency Graph
+## Docs workflow
-```
-+------------------+ +---------------------+
-| ci.yml |------->| |
-| (push/PR main) | | predeploy.yml |
-+------------------+ | (workflow_call) |
- | |
-+------------------+ | +-- build-and-lint |
-| docker-build.yml |------->| +-- docker-build |
-| (PR, Dockerfiles)| | +-- compose-test |
-+------------------+ | +-- test-install |
- | |
-+------------------+ +---------------------+
-| release.yml |------->| |
-| (tags, releases) | | v
-+------------------+ | +-- publish-npm
- | +-- publish-github-packages
- +---------------------+
-
-+------------------+
-| docs.yml |------> Mintlify deployment
-| (docs-MachinaOs/)| (independent pipeline)
-+------------------+
-```
+**File:** [.github/workflows/docs.yml](../.github/workflows/docs.yml)
-### Key Design Decisions
-
-- **Reusable `predeploy.yml`**: Single source of truth for validation logic. All entry-point workflows delegate to it, avoiding duplication.
-- **Composite setup action**: Node.js, Python, and uv installation centralized in `.github/actions/setup/action.yml`. Workflows pass version overrides as inputs.
-- **`fail-fast: false` in test-install**: All 6 OS/Node combinations run to completion, giving visibility into platform-specific failures even when one platform fails.
-- **Docker layer caching via GHA**: `cache-from: type=gha` reuses layers across runs, reducing Docker build times.
-- **Scoped `docker-build.yml`**: Prevents full Docker rebuild on every PR -- only triggers when Dockerfile or compose files change.
-- **Dual npm publish**: Unscoped `machina` for public npm, scoped `@zeenie-ai/machina` for GitHub Packages. The scoped name is rewritten at publish time, not in source.
+Triggers on push to `docs-MachinaOs/**` on main + manual dispatch. Single job: install Mintlify CLI, run `mintlify deploy` with `MINTLIFY_TOKEN`. No predeploy gate — docs are static, independent of the application's build.
---
-## Source Files
-
-| File | Lines | Description |
-|------|-------|-------------|
-| `.github/workflows/ci.yml` | 15 | CI entry point, delegates to predeploy |
-| `.github/workflows/predeploy.yml` | 157 | Reusable validation (build, lint, Docker, install) |
-| `.github/workflows/release.yml` | 73 | Predeploy gate + dual npm publish |
-| `.github/workflows/docker-build.yml` | 18 | Docker-scoped PR validation |
-| `.github/workflows/docs.yml` | 33 | Mintlify documentation deployment |
-| `.github/actions/setup/action.yml` | 37 | Composite action: Node.js + Python + uv |
+## Source files
+
+| File | Purpose |
+|------|---------|
+| `.github/workflows/ci.yml` | CI entry point |
+| `.github/workflows/predeploy.yml` | Reusable validation (plan + pre-commit + build/lint + tests + OS matrix + alls-green) |
+| `.github/workflows/release.yml` | Tag-triggered release pipeline (dry-run default on manual) |
+| `.github/workflows/publish-pypi.yml` | Reusable: build wheel + sdist + OIDC trusted publish |
+| `.github/workflows/rollback.yml` | Manual deprecate + revert PR |
+| `.github/workflows/codeql.yml` | SAST (Python + JS/TS) |
+| `.github/workflows/check-zizmor.yml` | Workflow-security linter |
+| `.github/workflows/test-install.yml` | Cross-platform user-install smoke |
+| `.github/workflows/docs.yml` | Mintlify documentation deploy |
+| `.github/actions/setup/action.yml` | Composite: pnpm + Node + Python + uv |
+| `.github/dependabot.yml` | Weekly grouped updates (npm + pip × 2 + actions) |
+| `.pre-commit-config.yaml` | ruff + prettier + eslint + actionlint hooks |
+| `.python-version` | Toolchain pin (`3.12`) — single source of truth |