SLT.BETA.019 – Git hosting enforcement matrix and guidance

[flyingrobots]

[SLT.BETA.019] Git hosting enforcement matrix and guidance

Overview

Document enforcement capabilities and recommended Shiplog setups across major Git hosting providers so teams can configure protections correctly.

References & Assets

• Figma / Design: N/A
• Product Spec (Notion / Confluence): N/A
• Related Issues / PRs: SLT.BETA.020, SLT.BETA.021, docs runbooks
• Feature Flags / Experiments: N/A
• Other Assets: docs/hosting/github.md

User Story

As a team adopting Shiplog on different Git hosts, I want clear guidance on enforcement options per provider, so that we configure refs, rulesets, and hooks correctly.

Acceptance Criteria

• docs/hosting/matrix.md published with per-host capabilities table
• Guidance covers GitHub.com, GitHub Enterprise, GitLab SaaS/self-managed, Gitea, and Bitbucket Cloud/Data Center
• Includes recommendations for branch namespace vs custom refs, hooks, and required checks
• Cross-links added from existing hosting docs and README

Definition of Done

Matrix doc live, referenced from README and runbooks, with actionable recommendations for each host.

Scope

In-Scope

• New hosting matrix document
• Updates to existing hosting/runbook pages and README

Out-of-Scope

• Automated detection of host capabilities
• CI template emission (covered elsewhere)

Deliverables

• Est. Lines of Code: ~120 (docs)
• Est. Blast Radius: docs/hosting, README.md

Implementation Details

High-Level Approach

Create matrix table summarizing enforcement knobs per host, add explanatory sections, and update references throughout docs.

Affected Areas

• docs/hosting/matrix.md
• docs/hosting/github.md
• docs/runbooks/github-protection.md
• README.md

Implementation Steps

• Draft matrix with capabilities and recommendations per host
• Review with maintainers for accuracy
• Link matrix from README and host-specific docs
• Add follow-up tasks/notes for CI templates

Test Plan

Happy Path

• Docs render correctly locally (mdlint)

Edge Cases

• Links verified using markdownlint and link checker

Failure Cases

• N/A (documentation update)

Monitoring & Success Metrics

• Docs site build passes in CI

QA Sign-off Matrix

Environment	Surface	Owner	Status	Notes
Docs build	Markdown	TBD	Pending	Validate via markdownlint

Requirements

Hard Requirements

• Provide clear recommendation for each host regarding namespace and enforcement

Soft Requirements

• Include example workflows or references where available

Runtime Requirements

• N/A (documentation)

Dependencies & Approvals

• Docs review

---

Production Notes

Priority: 3 / 5

Necessary foundation for Beta onboarding (P2).

Complexity: 2 / 5

Primarily documentation with research.

Estimate: 6 - 10 hours

Includes research, drafting, review.

Risk & Rollback

• Primary Risks: Inaccurate guidance causing misconfiguration
• Mitigations: Cross-check with host docs; reviewer approval
• Rollback / Kill Switch: Revert doc changes

---

Additional Notes

Consider adding workflow snippets as follow-up tasks.