feat(bootstrap-repo): environments + required reviewers (last v0.2-deferred item)

The remaining VALIDATION.md deferred item from v0.1: environment
protection + required-reviewer flows in bootstrap-repo. Now ships.

Config shape (under targets.github):

  "environments": {
    "pypi": {
      "wait_timer": 0,
      "prevent_self_review": true,
      "reviewers": [
        { "type": "User", "id": 12345 },
        { "type": "Team", "id": 67890 }
      ],
      "deployment_branch_policy": {
        "protected_branches": false,
        "custom_branch_policies": true
      }
    },
    "staging": { "wait_timer": 5 }
  }

Each environment becomes one PUT /repos/<repo>/environments/<name>
call. Step name in the report: `environment:<name>` so multiple
envs surface independently. Dry-run prints what would PUT;
--apply runs it and surfaces success or the GitHub error body.

3 new tests (184 total):
- dry-run lists both pypi + staging
- apply hits the API endpoint and reports `ok`
- no `environments` block -> no `environment:*` steps emitted

bootstrap-repo verb is now feature-complete relative to the
v0.1 design (topics + branch protection + environments).

Author: imanimanyara

src/release_kit/platforms/git_hosts/github.py

@@ -63,6 +63,24 @@ def __post_init__(self) -> None:
         self._branch_protection: dict[str, object] | None = (
             dict(bp) if isinstance(bp, dict) else None
         )
+        # Optional declarative environments + required reviewers.
+        # Shape (mirrors PUT /repos/{owner}/{repo}/environments/{name}):
+        #   environments:
+        #     pypi:
+        #       wait_timer: 0
+        #       prevent_self_review: true
+        #       reviewers:
+        #         - { type: User, id: 12345 }
+        #         - { type: Team, id: 67890 }
+        #       deployment_branch_policy:
+        #         protected_branches: false
+        #         custom_branch_policies: true
+        envs = extras.get("environments")
+        self._environments: dict[str, dict[str, object]] = (
+            {str(k): dict(v) for k, v in envs.items() if isinstance(v, dict)}
+            if isinstance(envs, dict)
+            else {}
+        )
 
     def authenticate(self, ctx: RunContext) -> StepOutcome:
         if not self._repo or "/" not in self._repo:

src/release_kit/workflows/bootstrap_repo.py

@@ -121,6 +121,42 @@ def run_bootstrap(config: Config, *, apply: bool = False) -> RunReport:
                             StepOutcome("branch_protection", "failed", str(e), error=e)
                         )
                         report.failures.append(outcomes[-1])
+
+            # Environments + required reviewers (PUT /repos/.../environments/<name>)
+            for env_name, env_body in plat_obj._environments.items():
+                env_path = f"/repos/{plat_obj._repo}/environments/{env_name}"
+                if ctx.dry_run:
+                    outcomes.append(
+                        StepOutcome(
+                            f"environment:{env_name}",
+                            "dry-run",
+                            f"would PUT {env_path}",
+                        )
+                    )
+                    continue
+                try:
+                    plat_obj._api_put(
+                        ctx, env_path, json=env_body, env_var=plat_obj._env_var
+                    )
+                    reviewers = env_body.get("reviewers")
+                    n_reviewers = len(reviewers) if isinstance(reviewers, list) else 0
+                    outcomes.append(
+                        StepOutcome(
+                            f"environment:{env_name}",
+                            "ok",
+                            f"applied (reviewers={n_reviewers})",
+                        )
+                    )
+                except PlatformError as e:
+                    outcomes.append(
+                        StepOutcome(
+                            f"environment:{env_name}",
+                            "failed",
+                            str(e),
+                            error=e,
+                        )
+                    )
+                    report.failures.append(outcomes[-1])
         else:
             outcomes.append(
                 StepOutcome("topics", "skipped", "bootstrap not yet implemented for this host")

tests/workflows/test_workflows.py

@@ -340,6 +340,76 @@ def test_bootstrap_apply_calls_branch_protection_endpoint(
     assert body.get("enforce_admins") is True
 
 
+def test_bootstrap_dry_run_environments(
+    clean_env: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("GITHUB_TOKEN", "ghp_x")
+    cfg = _make_config(
+        github={
+            "enabled": True,
+            "auth": "token",
+            "repo": "o/r",
+            "tag": "v1.0.0",
+            "environments": {
+                "pypi": {
+                    "wait_timer": 0,
+                    "reviewers": [{"type": "User", "id": 12345}],
+                },
+                "staging": {"wait_timer": 5},
+            },
+        }
+    )
+    report = run_bootstrap(cfg, apply=False)
+    steps = report.target_outcomes["github"]
+    env_steps = [s for s in steps if s.step.startswith("environment:")]
+    assert len(env_steps) == 2
+    assert all(s.status == "dry-run" for s in env_steps)
+    env_names = {s.step for s in env_steps}
+    assert env_names == {"environment:pypi", "environment:staging"}
+
+
+@respx.mock
+def test_bootstrap_apply_calls_environment_endpoint(
+    clean_env: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("GITHUB_TOKEN", "ghp_x")
+    route = respx.put(
+        "https://api.github.com/repos/o/r/environments/pypi"
+    ).mock(return_value=httpx.Response(200, json={"name": "pypi"}))
+    cfg = _make_config(
+        github={
+            "enabled": True,
+            "auth": "token",
+            "repo": "o/r",
+            "tag": "v1.0.0",
+            "environments": {
+                "pypi": {
+                    "wait_timer": 0,
+                    "reviewers": [{"type": "User", "id": 12345}],
+                },
+            },
+        }
+    )
+    report = run_bootstrap(cfg, apply=True)
+    steps = report.target_outcomes["github"]
+    env_step = next(s for s in steps if s.step == "environment:pypi")
+    assert env_step.status == "ok"
+    assert route.called
+
+
+def test_bootstrap_no_environments_emits_no_step(
+    clean_env: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Without an `environments` block, no environment:* steps emit."""
+    monkeypatch.setenv("GITHUB_TOKEN", "ghp_x")
+    cfg = _make_config(
+        github={"enabled": True, "auth": "token", "repo": "o/r", "tag": "v1.0.0"}
+    )
+    report = run_bootstrap(cfg, apply=False)
+    steps = report.target_outcomes["github"]
+    assert not any(s.step.startswith("environment:") for s in steps)
+
+
 def test_bootstrap_no_branch_protection_emits_no_step(
     clean_env: None, monkeypatch: pytest.MonkeyPatch
 ) -> None: