api/.github/BRANCH_PROTECTION.md

Default branch protection

master is changed through pull requests. Do not push or publish directly to the default branch, including through automation or the Git Data API.

Normal publishing flow

1. Create a scoped agent/* or feature branch from the current origin/master.
2. Commit and push only the intended changes.
3. Open a pull request targeting master.
4. Wait for the Required CI check. If master moves, update the branch and wait for the strict check to rerun.
5. Resolve every review conversation and squash-merge the pull request.
6. Confirm the post-merge Release Manager gate completes on master.

The aggregate check covers the PHP unit, integration, API, and legacy matrix, plus Edge Agent, Edge Broker, and Edge Gateway Backend. Qodana is advisory and the Release Manager gate is intentionally post-merge.

Desired ruleset

rulesets/protect-default-branch.json is the importable final desired-state repository-ruleset request body. For the initial POST, copy the file and override enforcement to disabled. Inspect the normalized ruleset and verify a green preparation PR and post-merge run, then PUT the exact committed file to activate it.

The desired rule targets ~DEFAULT_BRANCH, requires pull requests with zero approvals, conversation resolution, strict Required CI from GitHub Actions integration 15368, squash-only linear history, and blocks deletion and force pushes. Repository administrators receive pull-request-only bypass; they do not receive a standing direct-push bypass.

When the ruleset is activated, align repository settings at the same time: retain squash merging, disable merge commits and rebase merging, enable auto-merge and branch-update suggestions, delete merged branches automatically, keep the Actions token read-only, and prevent Actions from approving reviews.

Activation record

Repository ruleset 19041620 was activated on 2026-07-16 after preparation PR #311 passed Required CI and the merged master commit passed both Required CI and the Release Manager gate. This documentation update is the after-activation canary for the normal protected pull-request path.

Break glass

When an incident cannot wait for the normal gate:

1. Open a pull request and describe the incident, risk, and reason for bypass.
2. Have a repository administrator use the pull-request-only bypass.
3. Monitor Required CI and the post-merge Release Manager workflow.
4. Open a follow-up pull request for any deferred validation or remediation.

Never bypass by updating refs/heads/master directly. Ruleset changes and emergency bypasses must remain visible in GitHub's audit trail.