Skip to content

deploygov: deployment governance — docs / website / e2e sweep #697

Description

@babltiga

Part of #682 (deployment approval governance epic — read it first for the big picture).

Goal

The documentation / website / drift sweep — deliberately last, once the implemented surface is stable. Every file below changes in this issue unless an earlier sub-issue already carried its slice (e.g. docs/04-api-spec.md endpoint sections land with their features; verify completeness here).

Steps

  1. docs/18-deployment-governance.md — new chapter in the shape of docs/17-api-governance.md: concept, module layout, data model summary, lifecycle diagram, gate contract (fail-closed semantics spelled out), freeze-window semantics, break-glass compensating controls, CI wrapper usage per provider, service-account API-key setup.
  2. Existing docs — verify/complete:
    • docs/02-architecture.md — module map + request flow addition.
    • docs/03-data-model.md — all eight tables + three pg enums with columns/indexes.
    • docs/04-api-spec.md — full endpoint audit against the implemented controllers.
    • docs/05-backend.md — deploygov module section + the two scheduled jobs in the job registry.
    • docs/06-frontend.md — new routes/pages/api modules.
    • docs/07-security.md — authorization matrix rows (PERM_DEPLOYMENT_PIPELINE_MANAGE, PERM_DEPLOYMENT_REVIEW, per-pipeline grants), API-key-only endpoints, self-approval rule, fail-closed gate.
    • docs/08-notifications.md — five event types (if not fully landed in deploygov: deployment governance — notifications & audit fan-out #695).
    • docs/09-deployment.md — new env vars (ACCESSFLOW_DEPLOYGOV_TIMEOUT_CHECK, ACCESSFLOW_DEPLOYGOV_RELEASE_CHECK, any others added).
    • docs/12-roadmap.md — new ## v2.4 🚧 in progress section: - **Deployment approval governance** — <prose description naming the tables, gate endpoint, CI wrappers, freeze windows, break-glass> (AF-682).
  3. README.md — features list + project-structure notes (new ci-templates/azure/, new actions) + quick-start mention if applicable.
  4. website/ — feature tile + roadmap entry in website/index.html (move/add under the appropriate roadmap group), paragraph in website/docs/index.html, new content-source-map row in website/README.md, bump sitemap.xml <lastmod> and JSON-LD dateModified per .claude/patterns/website-drift.md.
  5. CLAUDE.md — add the deploygov module to the module tree listing (one line, matching the existing format).
  6. Screenshots — if the release adds visible pages to the website, regenerate via e2e/screenshots/capture.ts per the release process (coordinate with release prep; not blocking this issue).

Acceptance criteria

  • prep-gh-release's roadmap gate would pass for v2.4: every (AF-682) reference resolves, the epic and all sub-issues are closed and documented.
  • The website CI guards (frontend area job) pass — anchor contract frontend/src/config/docs.tswebsite/app.js intact, sitemap lastmod bumped.
  • docs/04-api-spec.md lists every implemented deploygov endpoint (diffed against the controllers).
  • Docs build/lint checks in CI pass; no drift warnings from the af-reviewer checklist for website-drift.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions