feat(cicd): 36605 changelog auto-publish to dev site

[sfreudenthaler]

What

End-to-end implementation of automated release changelog publishing to dev.dotcms.com, spec-first (speckit flow: spec → plan → tasks → TDD implementation → adversarial verification), plus two CI-hygiene cleanups. All pieces are independently mergeable — no dependency on #36416 or any other open PR.

1. Spec (specs/36605-changelog-site-publish/)

Spec (13 FRs incl. human-edit protection, no-auto-backfill, older-version patch semantics; LTS/CLI descoped v1) plus data-model.md (live-verified Dotcmsbuilds field contract). The working artifacts (plan/tasks/research/checklists — incl. Constitution Check and ADR-gate consultation, 3 relevant ADRs, none conflicting; 44/44 TDD tasks complete) were used during development and deliberately not committed.

2. Implementation

• .github/actions/core-cicd/changelog-publisher/ — new Python CLI (mirrors the evergreen-tracks package pattern): searches Dotcmsbuilds by version (minor_dotraw), upserts create/update-in-place, fires the System Workflow Publish action with disabledWYSIWYG:["releaseNotes"] (markdown-preservation guard). Dry-run by default; --apply to fire; --force (manual only) to override human-edit protection, which skips any entry last modified by a non-service-account user (immutable modUser id comparison, display-name fallback). Exit contract: 0 = success/protective-skip (::changelog-skip:: marker), 2 = validation (out-of-scope version rejected before any network call), 1 = runtime failure. 27 pytest (responses-mocked) green.
• Single-inference design: there is no separate site-notes generation. The existing gather-release-data/prompt-template.md becomes the one shared editorial template (site style: prose intro, no emoji, site section set, [[#N](issues url)] links), the GitHub release body is the single shared artifact, and the publisher injects the site's per-version heading anchors mechanically at publish time. One inference per release; the site path has zero Claude dependency at publish time; a hand-edited GitHub release re-syncs the site on re-run. Note: this restyles the GitHub releases page to the site's editorial format (deliberate).
• .github/workflows/cicd_comp_changelog-site-publish-phase.yml + additive job in cicd_6-release.yml — runs after release-notes (fetches the published release body via gh release view), gated on is_latest (current-track GA only: excludes CLI/LTS), non-blocking (continue-on-error; a publish failure can never fail a release), serialized per version via a concurrency group. Slack notices to #dot-releases (CE1TBQU00) on failure, protective skip, and pre-publisher step failure (catch-all if: failure()).

3. CI hygiene (independent commits)

• Moved the evergreen-tracks uv package from top-level cicd/ into .github/actions/core-cicd/ (64 tests pass from new home).
• Deleted orphaned cicd/resources/update_osgi_plugins.py (caller removed Feb 2024 in #27655: release fixes for lts #27667; no consumer repo- or org-wide) — the top-level cicd/ folder is gone.

Operational prerequisites before first live run (not code)

1. Provision a dedicated service account on corpsites-headless + JWT as release secret DOTCMS_DEVSITE_TOKEN.
2. Set repo var DOTCMS_DEVSITE_SERVICE_ACCOUNT to that account's modUser id (unset = all updates skip protectively).
3. SLACK_BOT_TOKEN must be available to the release workflow (existing secret, new consumer).
4. First release after merge: watch #dot-releases and the changelog page — there is no non-prod corpsites, so the maiden --apply is the real end-to-end test (manual dry-run checklist in the package README).

Verification

Adversarially reviewed by an independent pass: FR conformance in code, token-leak grep, workflow needs/if semantics vs the real release pipeline, docker-tag emit-order trace, and date-format acceptance traced through ContentletAPI.DEFAULT_DATE_FORMATS. All findings fixed (5bd97cac13).

Closes: #36605 (feature issue, under epic #35693)

🤖 Generated with Claude Code

https://claude.ai/code/session_012ogYXVeZsBVUHkwzdStYPJ

[claude]

Claude finished @sfreudenthaler's task in 6m 7s —— View job

---

Claude finished @sfreudenthaler's task in 5m 39s —— View job

---

PR Review — changelog auto-publish to dev site

This is a well-structured, well-tested addition. The design is sound: dry-run default, non-blocking in the release pipeline, per-version concurrency serialization, human-edit protection via immutable modUser, and the single-artifact (GitHub-body-is-site-content) approach. Findings below are all non-blocking.

New Issues

• 🟡 Medium: .github/actions/core-cicd/changelog-publisher/src/changelog_publisher/publisher.py:33-38 (used at :127) — a transient HTTP error during the post-create read-back poll turns a successful create into a reported failure. _wait_until_searchable calls client._search, which calls resp.raise_for_status(). If any poll gets a 5xx/timeout after the create's fire() already returned 200, the exception propagates out of publish(), the CLI catches it (cli.py:58) and returns 1, and Slack posts "Changelog site publish FAILED" even though the entry was written. The code comment states "Timeout is a warning, not a failure — the write itself succeeded", but only loop-exhaustion (returns False → warning) is handled gracefully; an exception mid-poll is not. No data corruption (a re-run idempotently updates in place), but it produces a misleading failure alarm. Wrap the _search call in _wait_until_searchable in a try/except requests.RequestException and treat it like the timeout branch (warn, don't fail). Fix this → (matching test gap: test_publisher.py covers the poll-sees-row and timeout cases, but not poll-raises-after-successful-create.)

• 🟡 Medium: .github/actions/core-cicd/changelog-publisher/src/changelog_publisher/client.py:88-93 — fire() only checks the HTTP status (raise_for_status()). Assumption: the dotCMS System Workflow fire endpoint can return HTTP 200 with a per-contentlet error inside the response entity (a common dotCMS pattern for validation/workflow errors). If so, a rejected publish would be reported as success, and no Slack alert fires. What to verify: confirm whether PUT /api/v1/workflow/actions/{id}/fire returns non-2xx on a rejected contentlet, or 200 with an error payload. If the latter, inspect resp.json() for an error/errors field before treating the fire as successful.

• 🟡 Medium: .github/actions/core-cicd/changelog-publisher/src/changelog_publisher/publisher.py:46,54 — the injected heading anchor uses only the heading's first word (m.group(1)), so any two sections whose first word matches collide to the same {#Word-<version>} anchor. Safe for the current fixed template (Features / Enhancements / Fixes / Deprecations / Infrastructure — all distinct first words), but the notes are the hand-editable GitHub release body, so an edited re-run (e.g. adding a second heading starting "Security…") would produce duplicate in-page anchors. Low likelihood given the controlled template; worth a comment noting the invariant, or slugging the full heading text.

Notes (non-blocking, no action needed)

• version.py:13 counter [0-9]{1,2} — confirmed intended by author (upstream releaser caps the index at two digits).
• ES index-lag guard (post-create read-back poll) — added per author follow-up; correctly addresses the sequential double-create window, and the workflow concurrency group covers the concurrent one.
• Token handling is clean: read once, sent only as the Authorization header, never logged; the test_cli.py leak-grep tests (stdout/stderr/caplog) are a good guard.
• Workflow error branching (set +e / capture RC / if: failure() catch-all) correctly keeps the release green regardless of publisher outcome (FR-008).

No blocking issues.
• branch issue-36605-changelog-site-publish

[sfreudenthaler]

RE: the two medium findings

1. Search-then-create has no guard against Elasticsearch index lag on a retry: fixed with subsequent commit. Makes sure a read can happen before complete
2. The counter is restricted to 1–2 digits (-[0-9]{1,2}): As intended. there's an upstream limitation on the releaser for maximum of two character index as well.

[nollymar]

do we want to expose the corpsites URL as a default value in our public repo?