Configure branch protection and auto-merge policy for safe dependency deployment

[wax911]

Background

local-stack should support automated patch/minor dependency updates that flow through validation, OpenCode risk gating, merge into dev, and Doco-CD deployment. Major updates must not follow the automatic path and must require manual promotion.

This issue covers repository policy: branch protection, required checks, auto-merge behavior, and deployment gating expectations.

The repository deploys from dev.

Goals

• Configure dev branch protection for safe automated dependency merges.
• Ensure patch/minor dependency PRs can auto-merge only after required checks pass.
• Ensure major updates require manual promotion.
• Ensure OpenCode risk gate and stack validation are required before merge.
• Ensure Doco-CD deploys only after code is merged into dev, not from PR branches.
• Preserve manual control for risky updates.

Non-goals

• Do not implement the OpenCode workflow here.
• Do not implement the Doco-CD deploy runner here.
• Do not implement the operational runbook here.
• Do not deploy from GitHub Actions.

Required repository policy

The dev branch must be treated as the deployment branch.

Required branch protection should include:

• Require pull request before merging.
• Require status checks before merging.
• Require conversation resolution.
• Prevent force pushes.
• Prevent deletion.
• Restrict bypasses to repository admins/maintainers only if absolutely required.

Required checks should include at minimum:

Validate stack
Dependabot OpenCode gate

If workflow job names differ, update this list to match the actual GitHub check names after implementation.

Auto-merge policy

Patch/minor updates:

• May auto-merge after validation and OpenCode gate pass.
• May auto-deploy immediately after merge to dev through Doco-CD.
• Must still pass all branch protection requirements.

Digest-only updates:

• May auto-merge only if image name and tag are unchanged, validation passes, and OpenCode classifies the update as low risk.

Major updates:

• Must not auto-merge.
• Must not auto-deploy immediately.
• Must require manual promotion.
• Must include release/migration notes and rollback notes.

Unknown or mixed-risk updates:

• Must not auto-merge.
• Require human review.

Manual promotion requirement for major updates

A major dependency update PR must include or link to:

• Release notes.
• Breaking change notes.
• Current image/dependency version.
• Target image/dependency version.
• Affected services.
• Data/volume migration risk assessment.
• Backup confirmation where stateful services are involved.
• Rollback plan.

Interaction with Doco-CD

Doco-CD must deploy only from dev.

Doco-CD must not deploy PR branches.

Deployment trigger policy:

PR branch
  -> validation and OpenCode gate only
  -> merge to dev when allowed
  -> Doco-CD deploys dev

Never let a PR workflow deploy to the hosted machine.

Required implementation checks

The implementer must verify:

gh repo view AniTrend/local-stack --json defaultBranchRef,autoMergeAllowed

If auto-merge is disabled at repository level, either:

1. Enable GitHub auto-merge in repository settings and rely on branch protection, or
2. Implement a safe merge action that merges only when OpenCode output has automerge_allowed=true and all required checks pass.

Preferred option: use GitHub native auto-merge with branch protection.

Required GitHub Actions behavior

The OpenCode gate should not directly force-merge. It should provide a review signal and, where safe, enable/request auto-merge only after required checks pass.

If a merge action is used instead of native auto-merge, it must:

• Only run for Dependabot PRs.
• Only merge into dev.
• Only merge when OpenCode output says automerge_allowed=true.
• Only merge patch/minor or approved digest-only updates.
• Refuse major updates.
• Refuse unknown risk.
• Refuse if validation failed.
• Refuse if changed files include sensitive deployment files unexpectedly.

Acceptance criteria

• dev branch protection exists.
• Pull requests are required before merge to dev.
• Stack validation is required before merge.
• OpenCode risk gate is required before merge for Dependabot PRs.
• Patch/minor updates can auto-merge only after required checks pass.
• Major updates cannot auto-merge.
• Unknown-risk updates cannot auto-merge.
• Doco-CD is configured to deploy only from dev.
• Doco-CD does not deploy PR branches.
• A test major Docker update remains blocked.
• A test patch/minor Docker update can merge after checks pass.

Test plan

1. Create a test branch with a patch/minor Docker image bump.
2. Confirm validation passes.
3. Confirm OpenCode classifies it low risk.
4. Confirm auto-merge becomes available only after checks pass.
5. Confirm merge lands in dev.
6. Confirm Doco-CD deploys from dev.
7. Create a test branch with a major Docker image bump.
8. Confirm OpenCode blocks or requests changes.
9. Confirm auto-merge is not enabled.
10. Confirm Doco-CD does not deploy from the PR branch.

Related issues

• Dependabot/OpenCode gate issue.
• Doco-CD deploy runner issue.
• Doco-CD hardening and rollback runbook issue.