home / skills / openclaw / openclaw / merge-pr

merge-pr skill

safe

This skill automates deterministic squash merges with strict verification, head-SHA pinning, and post-merge attribution, ensuring safe PR integration.

npx playbooks add skill openclaw/openclaw --skill merge-pr

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.1 KB

---
name: merge-pr
description: Script-first deterministic squash merge with strict required-check gating, head-SHA pinning, and reliable attribution/commenting.
---

# Merge PR

## Overview

Merge a prepared PR only after deterministic validation.

## Inputs

- Ask for PR number or URL.
- If missing, use `.local/prep.env` from the PR worktree.

## Safety

- Never use `gh pr merge --auto` in this flow.
- Never run `git push` directly.
- Require `--match-head-commit` during merge.
- Wrapper commands are cwd-agnostic; you can run them from repo root or inside the PR worktree.

## Execution Contract

1. Validate merge readiness:

```sh
scripts/pr-merge verify <PR>
```

Backward-compatible verify form also works:

```sh
scripts/pr-merge <PR>
```

2. Run one-shot deterministic merge:

```sh
scripts/pr-merge run <PR>
```

3. Ensure output reports:

- `merge_sha=<sha>`
- `merge_author_email=<email>`
- `comment_url=<url>`

## Steps

1. Validate artifacts

```sh
require=(.local/review.md .local/review.json .local/prep.md .local/prep.env)
for f in "${require[@]}"; do
  [ -s "$f" ] || { echo "Missing artifact: $f"; exit 1; }
done
```

2. Validate checks and branch status

```sh
scripts/pr-merge verify <PR>
source .local/prep.env
```

`scripts/pr-merge` treats “no required checks configured” as acceptable (`[]`), but fails on any required `fail` or `pending`.

3. Merge deterministically (wrapper-managed)

```sh
scripts/pr-merge run <PR>
```

`scripts/pr-merge run` performs:

- deterministic squash merge pinned to `PREP_HEAD_SHA`
- reviewer merge author email selection with fallback candidates
- one retry only when merge fails due to author-email validation
- co-author trailers for PR author and reviewer
- post-merge verification of both co-author trailers on commit message
- PR comment retry (3 attempts), then comment URL extraction
- cleanup after confirmed `MERGED`

4. Manual fallback (only if wrapper is unavailable)

```sh
scripts/pr merge-run <PR>
```

5. Cleanup

Cleanup is handled by `run` after merge success.

## Guardrails

- End in `MERGED`, never `CLOSED`.
- Cleanup only after confirmed merge.

Overview

This skill provides a script-first, deterministic squash-merge flow for prepared pull requests. It enforces strict required-check gating, pins the merge to the PR head SHA, and produces reliable attribution and a persistent comment URL. The flow is safe, idempotent, and designed to be run from the repo root or the PR worktree.

How this skill works

It verifies required artifacts and status with a preflight command, then performs a one-shot deterministic squash merge pinned to the prepared HEAD SHA. The run phase selects a merge author email with fallback candidates, adds co-author trailers, verifies trailers post-commit, retries comment posting, and emits merge metadata (merge SHA, merge author email, comment URL). The wrapper refuses unsafe shortcuts like automatic GH merges or direct git push.

When to use it

Merging a prepared pull request that has associated review and prep artifacts
When you need deterministic attribution and reproducible merge commits
When required CI checks must be enforced and pending/failing checks must block merges
When you want a safe, repeatable merge flow that avoids accidental pushes or auto-merge
When you need an auditable comment URL and merge metadata for downstream automation

Best practices

Always create and populate the required prep artifacts (.local/prep.env, .local/prep.md, .local/review.md, .local/review.json) before invoking merge
Run scripts/pr-merge verify <PR> first and confirm no required checks are failing or pending
Do not bypass the wrapper with gh pr merge --auto or direct git push; use the provided run command
Keep the PR worktree or run from repo root; the wrapper is cwd-agnostic
Allow the wrapper’s single-author-email retry and the three comment-post attempts; check outputs for merge_sha, merge_author_email, and comment_url

Example use cases

A release branch where every merge must be deterministic and tied to a prepared head SHA
Automated workflows that need a stable merge SHA and reliable author attribution for downstream deployments
Teams that require strict gating on required CI checks before merges proceed
Personal automation that posts merge metadata (merge_sha, merge_author_email, comment_url) into tracking systems

FAQ

What inputs does the flow require?

Provide a PR number or URL. If omitted, the script reads .local/prep.env from the PR worktree to determine the target.

Can I run the commands from any directory?

Yes. The wrapper commands are cwd-agnostic and can be run from the repo root or inside the PR worktree.

What happens if required checks are missing?

The verify step treats no required checks configured as acceptable ([]). It fails if any required check is failing or pending.

What outputs should I expect after run completes?

The run step reports merge_sha, merge_author_email, and comment_url once the merge is confirmed MERGED.