82 lines
5.4 KiB
Markdown
82 lines
5.4 KiB
Markdown
# Merge Batch
|
|
|
|
`merge:batch` is the maintainer shortcut for merging multiple PRs in order while keeping the GitHub-only squash rule and delegating generated follow-up work to the protected canonical-sync PR lane.
|
|
|
|
## Prerequisites
|
|
|
|
- Start from a clean `main` that exactly matches `origin/main`.
|
|
- For a real merge, require pull-request-only strict branch protection with the four exact GitHub-Actions-owned checks, administrator enforcement, no applicable ruleset bypass actors, and no merge queue. Dry runs remain available without this server-side prerequisite.
|
|
- Make sure [`.github/MAINTENANCE.md`](../../.github/MAINTENANCE.md) is the governing policy.
|
|
- Have `gh` authenticated with maintainer permissions.
|
|
- Use this only for PRs that are already expected to merge; conflicting PRs still need the manual conflict playbook.
|
|
|
|
## Basic Usage
|
|
|
|
```bash
|
|
npm run merge:batch -- --prs 450,449,446,451
|
|
```
|
|
|
|
Add `--poll-seconds <n>` if you want a slower or faster status loop while checks settle.
|
|
|
|
If a PR changes any tracked file under a canonical `skills/<skill-id>/**` subtree, review the entire affected subtree at the exact current head commit, then attest to that immutable revision:
|
|
|
|
```bash
|
|
npm run merge:batch -- --prs 450 --reviewed-head <40-character-head-sha>
|
|
```
|
|
|
|
Use `--dry-run` to exercise local classification without approving a run or merging. An abbreviated or stale attestation is rejected.
|
|
|
|
## CI Intake Contract
|
|
|
|
- Before dependent required jobs do expensive setup or wait work, `pr-policy` runs the fork-safety classifier from the exact protected-base implementation and fails an unsafe fork diff early.
|
|
- That CI result is fail-fast evidence, not merge authority. `merge:batch` independently recomputes the complete decision from trusted `main` and remains the only command allowed to approve fork runs or merge the PR.
|
|
- `impact_profile` is shadow-only telemetry. It never skips a required job, test, review, or merge gate.
|
|
- Normal source PRs generate derived preview state once in `source-validation`; `artifact-preview` verifies the exact-head manifest and digest instead of generating the tree again.
|
|
- Canonical-sync PRs use the complementary path: `pr-policy` proves the exact reproduced tree, lightweight `source-validation` records that boundary, and `artifact-preview` confirms no generated drift. Final CI and CodeQL still run on the resulting `main` commit.
|
|
- Test timing is observational. Local deterministic sharding requires the explicit `npm run test:local -- --shard-index N --shard-count M` opt-in; required CI remains complete and unsharded.
|
|
|
|
## Happy Path
|
|
|
|
`merge:batch` will:
|
|
|
|
- fetch the exact base/head objects and classify the complete raw Git diff
|
|
- recompute changed-skill evidence with evaluator code materialized from the trusted `main` commit
|
|
- reject incomplete evidence coverage, deterministic quality/security/provenance regressions, and base/head drift
|
|
- allow only exact `source_repo` transitions recorded in the trusted protected-base provenance exception ledger; unrecorded or malformed transitions still fail closed
|
|
- for external PRs, poll for asynchronously-created fork runs and approve only runs waiting on `action_required` when every path, mode, object, size, and workflow identity is allowlisted
|
|
- for sensitive same-repository source changes, allow the guarded exception only when the PR author is the repository owner and the exact full head SHA is attested; collaborator-authored sensitive changes fail closed under the external safety policy
|
|
- wait for the latest required checks bound to the exact head SHA
|
|
- call GitHub's immediate squash-merge endpoint and continue only when it reports `merged: true`
|
|
- pull the protected `main`; its trusted workflow opens a canonical-sync bot PR for generated artifacts and contributor credits when needed
|
|
|
|
## What It Automates
|
|
|
|
- exact-head required-check polling
|
|
- handoff of post-merge contributor and artifact drift to the canonical-sync PR lane
|
|
|
|
## What It Does Not Automate
|
|
|
|
- PR-body rewriting or normalization
|
|
- closing or reopening PRs to refresh metadata or workflow runs
|
|
- conflict resolution on the PR branch
|
|
- manual judgment for risky skill changes
|
|
- semantic review when the distinct `manual-review-required` check is present; the review fingerprint covers the complete nearest skill directory, including nested examples, scripts, lockfiles, references, and assets
|
|
- README community-source audits when the source metadata is ambiguous
|
|
- fork-only edge cases that require contributor coordination outside GitHub permissions
|
|
- base-branch or head drift: stale evidence is discarded, the checkout must be refreshed to the current `origin/main`, and the batch must be rerun; there is no automatic retry
|
|
- auto-merge and merge-queue enrollment; deferred merge state is rejected
|
|
|
|
## When To Stop
|
|
|
|
Stop and switch to the manual playbook when:
|
|
|
|
- the PR is `CONFLICTING`
|
|
- `merge:batch` reports a check failure that needs source changes, not maintainer automation
|
|
- the PR needs a manual README credits decision
|
|
- an external PR's local diff contains a symlink, gitlink, executable mode, unknown path/type, oversized blob, or other non-allowlisted change
|
|
- the workflow run cannot be bound to the intended PR number, current head SHA, `pull_request` event, and trusted workflow definition
|
|
- fork approval or branch permissions are missing
|
|
- effective strict protection for `main` cannot be proven
|
|
|
|
In those cases, follow [Merging Pull Requests](merging-prs.md) and the relevant sections in [MAINTENANCE.md](../../.github/MAINTENANCE.md).
|