.github/workflows/

Purpose

CI/CD pipeline definitions. unified-ci.yml is the main pipeline (validate → test → security → status jobs); release.yml is manual-dispatch-only (see root AGENTS.md); others handle Dependabot automation, security scanning, docs, and evaluations.

Ownership

• unified-ci.yml — thin caller: validate (→ reusable-python-lint.yml), test (→ reusable-python-test.yml, both tests/ and simplenote_mcp/tests/ preserved as separate pytest processes), security (→ reusable-security-scan.yml, shared with monitoring-consolidated.yml), build_and_publish (→ reusable-docker-build.yml; pushes main/latest/date-SHA image tags, never version tags, since this workflow doesn't run on tags), local-test (→ reusable-local-test.yml), status (aggregation, stays inline — needs needs.*.result from sibling jobs in the same file). Blocks on version consistency and pre-commit run --all-files before test/build/security run. A failed validate leaves test / Test and security / Security uncreated (verified on #980's run), so it blocks merges although it isn't itself a required check. test/security job IDs are load-bearing: their displayed check names (test / Test, security / Security) are live required branch-protection status checks (validate / Validate is not required, despite existing) — do not rename these job IDs, or the internal name: field of the reusable workflows they call, without first reading the actual resulting check name off a live PR and updating branch protection in the same window (see the 2026-08-13 Phase 9 refactor for the verification protocol).
• security.yml, dependency-review.yml — Bandit/pip-audit/CodeQL-style scanning.
• auto-fix.yml — thin caller: resolve-target job (inline branch/fix-type allowlist validation, no checkout needed) → reusable-auto-fix-apply.yml (checkout target branch, ruff fix/commit/push — kept inline rather than script-extracted, since the target branch may predate this refactor and lack scripts/) → reusable-auto-fix-notify.yml (PR comment via .github/scripts/find-associated-pr.js/comment-auto-fix.js, summary). auto-merge.yml — thin caller: auto-merge (→ reusable-auto-merge-pr.yml) + dependabot-auto-merge (→ reusable-dependabot-auto-merge.yml, gated on github.actor/github.event_name at the caller job level, not inside the reusable workflow, since github.event_name inside a called workflow_call job is not reliably the original triggering event). Neither reusable workflow adds a checkout step — both are triggered by fork-reachable PR events with write-level permissions, so checking out PR content and require()-ing a script from it would be a "pwn request" vector; their github-script bodies stay inline instead. The claude-dependabot-merge.yml and claude-status-check.yml callers were removed on 2026-10-21: the org orchestrator in docdyhr/.github checks this repo itself and never dispatched them.
• evaluation-quality-gate.yml — thin caller: reusable-eval-quality-run.yml (the npm eval suite on Node 24 from package-lock.json via npm ci, gated on OPENAI_API_KEY presence, because every evals/*.yaml uses provider: openai; Dependabot/fork PRs get a placeholder that parses as skipped) → reusable-eval-quality-report.yml (PR comment + check-run via .github/scripts/post-quality-gate-comment.js/create-quality-gate-check.js). scripts/ci/parse_eval_results.py reads mcp-evals 2.x output: per eval, the grader's five 1–5 ratings, which pass at a mean ≥ 3.5; mcp-evals' all-zero placeholder (Error running evaluation:, when the grader's reply isn't plain JSON) is reported as ungraded and left out of the pass rate (graded evals only; none graded is an error). A crash, a non-zero mcp-evals exit or zero evals exits 1, so the run job fails visibly; it never reports 0 tests as "below threshold". mcp-evals needs Node ≥ 20.19 (require(esm)); under Node 18 every run crashed with ERR_REQUIRE_ESM. mcp-evaluations.yml ("Eval File Check") — thin caller: reusable-mcp-eval-pr-check.yml only (scripts/ci/validate_eval_yaml.py on changed evals/*.yaml, PR comment via .github/scripts/comment-eval-files-changed.js). Its former mclenhard/mcp-evals run was removed in 2026-10: it passed the .py server to mcp-evals, which only loads JS/TS (ERR_UNKNOWN_FILE_EXTENSION), so it never produced a result.
• release.yml — manual workflow_dispatch version bump/release (patch/minor/major); thin caller: reusable-release-prepare.yml (version bump via scripts/release/bump_version.sh, changelog via scripts/release/generate_release_changelog.sh, commit/push, tag the release PR's merge commit (not origin/main's HEAD) via scripts/release/tag_release_commit.sh, GitHub-Release — single job, see in-file overage note; the merge wait allows 5.5 h for someone to approve the bot PR's runs; the last step deletes the merged release/vX.Y.Z branch, which gh pr merge --auto --delete-branch can't do once auto-merge merges later) → reusable-release-build.yml (build/twine, then SBOM+vuln reports via scripts/generate_release_security_reports.py --python against a clean venv holding only the built wheel; no pre-commit here, since it runs after the tag and release exist and validate already runs it on every PR) → reusable-release-attach-reports.yml; docker-publish (→ docker-release.yml, which validates the tag and calls reusable-docker-build.yml with version, pushing the vX.Y.Z and X.Y.Z image tags to Docker Hub and GHCR; the Helm chart's default image.tag depends on these existing). docker-release.yml also takes workflow_dispatch with a tag input, to backfill an existing release's image. notify job stays inline in the caller. release-finish.yml — workflow_dispatch (tag, optional docker) recovery path for a release release.yml didn't finish (merge wait expired, build failed): tags the merged release/vX.Y.Z PR's commit if the tag is missing, creates the GitHub Release from the tag's CHANGELOG section if missing, then reruns reusable-release-build.yml + reusable-release-attach-reports.yml (and docker-release.yml if asked). Also regenerates reports for old tags: the build runs the report script from the workflow's own commit, not the tag. The attach step uses gh release upload --clobber, so a release's body and latest flag are never touched. update-version.yml — thin caller (reusable-version-sync.yml); triggers on v*.*.* tag push (also accepts workflow_dispatch with a manual tag input, for testing), syncs version references post-release via scripts/release/sync_version_references.sh.
• docs.yml — thin caller (docs build via reusable-docs-build.yml, Pages deploy via reusable-docs-deploy.yml, link check via reusable-docs-link-check.yml). monitoring-consolidated.yml — thin caller (reusable-security-scan.yml — parametrized for eventual reuse by unified-ci.yml's security job — reusable-health-check.yml, reusable-badge-check.yml — adopts scripts/validate-badges.py — reusable-monitoring-summary.yml). publish-pypi.yml — PyPI publish.
• reusable-*.yml — local workflow_call reusable workflows, each owned by and used only by the caller(s) listed against it above. Not standalone triggers; see the owning caller for on: semantics. Introduced 2026-08-12 as part of a phased thin-caller refactor (org-standard ≤80-line-per-file check) — the docdyhr org's usual pattern delegates to the separate docdyhr/.github repo (see security.yml below), but these use local composition instead by deliberate choice (no cross-repo versioning/tagging overhead for logic specific to this repo).

Local Contracts

• yaml.safe_load() is not sufficient to validate uses: lines. A YAML-valid-but-schema-invalid uses: value (e.g. a bare SHA with the tag comment misplaced, instead of owner/repo@<sha> # tag) parses cleanly but makes GitHub run zero jobs for every workflow referencing it. Only a schema-aware linter (actionlint) catches this class of bug — not currently run in CI. Run actionlint on any .github/workflows/*.yml edit before considering it done, especially SHA-pinning changes.
• github-script steps must pass untrusted values via env:, never interpolate ${{ needs.*.outputs.* }} / ${{ github.event.inputs.* }} / ${{ steps.*.outputs.* }} directly into the script: body — an injected value could break out of the JS string literal (script-injection). Read via process.env.* instead; see the existing pattern and comment in auto-fix.yml.
• dependabot.yml (one directory up, at .github/dependabot.yml) covers four ecosystems: pip, npm, docker, github-actions — keep all four current when adding a new dependency manager to the project.
• auto-merge.yml's dependabot-auto-merge job auto-approves and merges patch/minor Dependabot PRs, but skips any PR touching a security-sensitive package (cryptography, requests, urllib3, aiohttp — matched via contains() against dependency-names, so those PRs always fall through to manual review regardless of update type). Add to that list when a new security-sensitive dependency is introduced.
• main branch protection requires 3 status checks (configured 2026-08-11, contexts updated 2026-08-13 after the thin-caller refactor changed their displayed names): test / Test, security / Security, Dependency Review. Validate was never in the required list, so its post-refactor name (validate / Validate) isn't either. Renaming unified-ci.yml's test/security job IDs, or the internal name: field of reusable-python-test.yml/reusable-security-scan.yml, changes these check names again — update branch protection (gh api repos/docdyhr/simplenote-mcp-server/branches/main/protection --method PUT, see git history around 2026-08-13 for the exact JSON body shape) in the same window as any such rename, or every subsequent PR becomes permanently unmergeable.

Verification

• actionlint on any changed workflow file (manual — not yet wired into CI itself)
• Push/PR and watch the validate job in unified-ci.yml actually queues and runs

Child DOX Index

None.