Skip to content

docs: state that GITLAWB_ENFORCE_OWNER_PUSH defaults to true - #383

Closed
Gravirei wants to merge 2 commits into
Twigpine:mainfrom
Gravirei:fix/issue-26-split-4-config-policy
Closed

Gravirei wants to merge 2 commits into
Twigpine:mainfrom
Gravirei:fix/issue-26-split-4-config-policy

Conversation

@Gravirei

@Gravirei Gravirei commented Aug 28, 2026 •

Copy link
Copy Markdown
Contributor

Why

Reviewer 2 closed #224 on 2026-08-28 with a directive: split the work into four narrow PRs. This is Split PR 4 (configuration + operator policy) and addresses the P2 finding the reviewer assigned to it.

Two operator-facing docs contradicted the code that PR #330 landed. Config::enforce_owner_push declares default_value_t = true, .env.example sets =true, the README env-var table says "Defaults to true", and the runtime behavior matches. But SECURITY.md line 57 (the "Repository write authorization defaults" section) and README.md line 69 (the "Known limitations" prose) both still said the default was false. The runtime, .env.example, env-var table, and security prose were lying to operators in opposite directions.

What this PR changes

  • SECURITY.md — rewrite the owner-push limitation to lead with "defaults to true" and describe GITLAWB_ENFORCE_OWNER_PUSH=false as the explicit rolling-upgrade compatibility override.
  • README.md — same correction in the Known-limitations bullet.
  • crates/gitlawb-node/tests/owner_push_default_docs.rs — new regression test that reads the four surfaces at test time and asserts each independently says the default is true. Reverting either doc edit or flipping default_value_t back to false turns a named test red.

Boundaries covered

  • Producer: the clap default_value_t = true declaration in Config and the .env.example shipping default.
  • Persistence: none — no state.
  • Restart/restore: none — no restart concern.
  • Consumer/effect: operator reads SECURITY.md and README to learn the default.
  • Cleanup/failure: if a future doc edit reintroduces the wrong wording, the named test goes red on the named surface.

Why this is its own PR (and not part of #224)

Reviewer 2: "Use the tested configuration default as the source of truth. State that owner enforcement is enabled by default and describe GITLAWB_ENFORCE_OWNER_PUSH=false only as the explicit rolling-upgrade compatibility override. Consolidate the duplicate limitation sections." The reviewer called this out as the P2 finding for the policy split, not the post-receive or transport split. It does not need the outbox work, the ANS-104 work, or any of the cert/CLI changes to land.

Overlap with open PRs

This PR is safe to land independently. It does not require any sibling PR. No new migration. No new dependency. No new env var. No code path change.

Verification

cargo test -p gitlawb-node --test owner_push_default_docs
cargo fmt --all -- --check
cargo clippy -p gitlawb-node --tests -- -D warnings

The regression test was load-bearing-checked before committing: stashing the SECURITY.md edit made security_md_states_owner_push_default_is_true go red on the exact pre-fix prose; stashing the README edit made readme_known_limitations_states_owner_push_default_is_true go red on the exact pre-fix prose. The other two tests (.env.example row and the existing env-var table) stayed green on each revert, confirming each surface is checked independently.

Summary by CodeRabbit

  • Documentation
    • Updated security guidance to clarify that repository writes require owner authorization by default.
    • Documented that authentication alone does not grant push access, including for delegated or CI keys.
    • Clarified that the compatibility override temporarily disabling owner enforcement should only be used during upgrades.
  • Tests
    • Added checks to ensure the owner-enforcement default is consistently documented and configured across repository guidance and environment examples.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

crate:node gitlawb-node — the serving node and REST API

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants