content-factory/tasks/017-git-publishing-dry-run-and-commit.md

Task 017: Git Publishing Dry Run And Commit

Development description: Implement the Git-backed publishing path that builds a content bundle, runs best-effort generic Markdown/MDX dry-run validation, executes Admin-defined transforms on the runner host, and commits directly to the configured production branch.

Implementation Details

• Backend endpoints:
  • POST /api/articles/{article_id}/publishing/dry-run
  • POST /api/articles/{article_id}/publishing/create-commit
  • GET /api/articles/{article_id}/publishing/status
  • GET /api/articles/{article_id}/publishing/commits
• Content bundle includes:
  • Markdown/MDX article file.
  • Frontmatter JSON/YAML according to site mapping.
  • Referenced approved asset files.
  • Bundle manifest.
• Publishing behavior:
  • Materialize active versioned YAML/script config into checked-out site repo workspace.
  • Run transform script directly on runner host inside site repo workspace.
  • Run generic Markdown/MDX dry-run preview validation, not target-site build.
  • Commit directly to configured production branch.
  • Rely on target repo CI/CD after push.
  • Primary done state is PUBLISH_COMMIT_CREATED.
• Failure behavior:
  • Non-fast-forward push or conflict fails publish step.
  • No automatic rebase.
  • If delayed deployment verification fails, alert Admin/Editor and leave production commit in place.

Public Interface

• Editor runs publishing dry run after final approval.
• Editor creates publish commit after dry run passes.
• UI shows commit SHA, branch, repository, and opportunistic deployment status.

Acceptance Criteria

• TDD pre-requirement: before implementation, write one failing integration test against a temporary local Git repository proving a final-approved article can create a commit; add dry-run and failure tests one behavior at a time and record evidence in Result.
• Publishing cannot dry-run before final approval.
• Dry run fails if generic Markdown/MDX content-shape validation fails.
• Publish commit cannot run until dry run passes.
• Content bundle uses site-configured path templates and frontmatter mapping.
• Active YAML/script config version is included in publish logs/manifest.
• Publish writes commit to configured production branch in a test repository.
• Non-fast-forward push or conflict fails without automatic rebase.
• Publish commit record stores repository URL, branch, commit SHA, bundle manifest, and status.
• UI clearly labels validation as best-effort content-shape validation only.

Verification

• Run publishing integration tests using a local bare Git repository.
• Run generic preview validation tests.
• Run Docker Compose smoke flow from final approval to publish commit against a demo site repo.

Result

• Status: Pending execution.
• TDD plan: To be filled during execution.
• Red evidence: To be filled during execution.
• Green evidence: To be filled during execution.
• Refactor notes: To be filled during execution.
• Verification output: To be filled during execution.