infra: adopt Mergify daily merge queue and PR dependency workflow

Summary

Adopt a controlled Mergify daily merge workflow for dev to reduce stale-base failures, merge conflicts, and accidental merges of pull requests that still require review work.

The workflow starts with serial merging only. It preserves existing GitHub branch protections and does not bypass reviews, required checks, or resolved conversations.

Problem

OpenShield contributors work on pull requests in parallel. A pull request can pass CI on an older dev commit but fail, conflict, or invalidate another change after another pull request merges. Reviewers also need a clear way to see whether a pull request is blocked by another pull request.

Objective

Use Mergify every day to test each eligible pull request on the latest dev state immediately before merge. Prevent merge when review, CI, conversation, or declared dependency requirements are not satisfied.

Success criteria

• dev remains green during daily operation.
• Mergify respects existing GitHub branch protection rules.
• Eligible pull requests are validated against the latest dev state before merge.
• Pull requests with failing CI, a draft state, unresolved conversations, an active change request, or an unresolved declared dependency do not merge.
• Maintainers record queue outcomes, rejected entries, detected conflicts, and configuration changes in this issue.
• A maintainer reviews queue outcomes every day and immediately records any safety concern.

Non-goals

• No batch merging, parallel queues, automatic conflict resolution, or merge bypass.
• No automatic declaration of pull-request dependencies.
• No modification to existing CI workflows.
• No DUSK rollout until the OpenShield workflow is reviewed and accepted.

Required authorization and ownership

Activity	Owner	Notes
Install and authorize the Mergify GitHub App	Organization owner or repository administrator	Limit app access to openshield-org/openshield.
Review app permissions and branch-protection compatibility	Repository maintainer	Do not grant broad bypass permissions.
Configure and monitor the workflow	Repository maintainer	Preserve GitHub protections.
Review operating evidence and decide DUSK rollout	Maintainer and owner	Required before applying this design to DUSK.

GitHub Actions remains the CI system. Mergify reads pull-request state and operates the merge queue. It does not replace existing workflows or require repository-stored credentials.

Proposed merge policy

A pull request is eligible for the queue only when all conditions are true:

• Required GitHub Actions checks are successful.
• At least one required approving review is current for the latest push.
• No active CHANGES_REQUESTED review exists.
• All review conversations are resolved.
• The pull request is not a draft.
• Every declared dependency has merged.

The queue processes one pull request at a time and retests it against the current dev branch before merge.

Dependency workflow

Declare known dependencies in the pull-request description:

Depends-On: #123

A pull request that declares Depends-On: #123 remains blocked until pull request #123 merges. Mergify then evaluates it again against the latest dev state.

Add this to the pull-request template:

## Dependencies
Depends-On: none

Authors replace none with one or more pull-request references when required. This is an explicit declaration, not an automatic guess.

Overlap detection, follow-up work

A separate GitHub Action may later identify likely overlap between open pull requests by checking API contracts, database migrations, dependency manifests, CI workflows, and source paths.

Its output must be advisory, for example: Possible overlap with #123: both modify the evaluation API contract. Authors and reviewers decide whether the overlap is a real dependency, a conflict risk, or unrelated work.

Inactive-author process

1. Apply awaiting-author after required changes are requested and the author is inactive.
2. After five working days, a maintainer may take over the branch, open a replacement pull request, or remove a dependency that review confirms is unnecessary.
3. Record the decision in the pull request before changing ownership or dependency state.

Rollout and daily operation

Phase 1: installation and safety check

• Owner installs Mergify for this repository only.
• Maintainer reviews requested app permissions.
• Maintainer confirms that branch-protection conditions are enforced by the queue.
• Maintainer creates a serial queue configuration with no batch or bypass behavior.

Phase 2: daily operation

• Queue every eligible approved pull request as part of normal daily work.
• Monitor every queue entry, retest, rejection, conflict, and merge outcome.
• Record each queue outcome, rejection, conflict, and configuration change in this issue.
• Pause the queue immediately if it bypasses a protection or produces unexpected merge behavior.

Phase 3: ongoing governance

• Publish an initial operating summary after the first five queue outcomes.
• Retain the configuration while it meets the safety criteria. Revise or pause it immediately if it does not.
• Consider the same configuration for DUSK only after OpenShield approval.

Evidence required before closing

• Link to the reviewed Mergify configuration pull request.
• Link to at least one queued pull request and its final CI result on the updated branch state.
• Confirmation that GitHub protections remained enforced.
• List of dependency declarations and any overlap alerts observed.
• Initial daily-operation summary, including failures or false alerts.
• Final maintainer decision.

Security constraints

• Do not store tokens, secrets, or credentials in .mergify.yml, workflows, issues, or pull-request descriptions.
• Do not configure Mergify as a broad protection bypass actor.
• Do not allow a queue rule to merge a pull request that GitHub branch protection would reject.
• Limit the app installation to the OpenShield repository.

Start by reviewing the repository's existing GitHub branch protections and GitHub Actions workflows, then confirm the required Mergify app permissions with a repository maintainer. Prepare the serial queue configuration in .mergify.yml and the dependency section in the pull-request template. Done means a reviewed configuration pull request, documented queue outcomes, and evidence that protections remained enforced after the first five outcomes.