From d2e26184744c016c324ff1ecce7851483f09a4e9 Mon Sep 17 00:00:00 2001 From: James Cruce Date: Sun, 2 Aug 2026 14:22:30 -0400 Subject: [PATCH] fix(land-and-deploy): correct the --auto failure diagnosis in Step 4 Step 4 says `--auto` failing means "repo doesn't have auto-merge enabled". That is only one of two causes, and in practice it is the rarer one. `--auto` only QUEUES a merge behind pending required checks. When every required check has already settled -- or the repo declares no required status checks at all -- GitHub considers the PR immediately mergeable and rejects enablePullRequestAutoMerge with "Pull request is in clean status" or "Pull request is in unstable status". Auto-merge being enabled makes no difference. A repo with zero required status checks takes the direct path 100% of the time, and so does any repo whose CI finishes before Step 4 runs. The flow itself is fine -- the direct-merge fallback already handles both cases. The problem is the recorded reason: an operator reading MERGE_PATH=direct is told to go check whether auto-merge is enabled, which sends them to the wrong setting. I lost time to exactly that on a repo where auto-merge was enabled the whole time and the ruleset simply had no required checks. Also adds --squash to the --auto invocation. The fallback squashes, so without it the two paths merge with different strategies depending on which one happens to be taken. Docs-only. Regenerated with `bun run gen:skill-docs` (and verified clean for --host codex and --host factory); output is idempotent on re-run, so the Skill Docs Freshness gate stays green. Co-Authored-By: Claude Opus 5 --- land-and-deploy/SKILL.md | 16 ++++++++++++++-- land-and-deploy/SKILL.md.tmpl | 16 ++++++++++++++-- 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/land-and-deploy/SKILL.md b/land-and-deploy/SKILL.md index 54ebf52c0f..367c9c337c 100644 --- a/land-and-deploy/SKILL.md +++ b/land-and-deploy/SKILL.md @@ -1475,13 +1475,25 @@ Record the start timestamp for timing data. Also record which merge path is take Try auto-merge first (respects repo merge settings and merge queues): ```bash -gh pr merge --auto --delete-branch +gh pr merge --squash --auto --delete-branch ``` If `--auto` succeeds: record `MERGE_PATH=auto`. This means the repo has auto-merge enabled and may use merge queues. -If `--auto` is not available (repo doesn't have auto-merge enabled), merge directly: +`--auto` fails for two unrelated reasons. Both fall through to the direct merge below, so +the flow is unaffected — but do not report the second one as "auto-merge is disabled": + +1. **Auto-merge is disabled for the repo** — `Auto-merge is not allowed for this repository`. +2. **The PR is not waiting on anything.** `--auto` only *queues* a merge behind pending + required checks. When every required check has already settled — or the repo declares + no required status checks at all — GitHub treats the PR as immediately mergeable and + rejects the mutation: + `Pull request is in clean status` (everything green) or + `Pull request is in unstable status` (something red, but nothing required). + A repo with zero required status checks therefore takes the direct path 100% of the + time no matter how auto-merge is configured, and so does any repo whose CI finishes + before this step runs. ```bash gh pr merge --squash --delete-branch diff --git a/land-and-deploy/SKILL.md.tmpl b/land-and-deploy/SKILL.md.tmpl index 98976ad020..78c3cffc28 100644 --- a/land-and-deploy/SKILL.md.tmpl +++ b/land-and-deploy/SKILL.md.tmpl @@ -598,13 +598,25 @@ Record the start timestamp for timing data. Also record which merge path is take Try auto-merge first (respects repo merge settings and merge queues): ```bash -gh pr merge --auto --delete-branch +gh pr merge --squash --auto --delete-branch ``` If `--auto` succeeds: record `MERGE_PATH=auto`. This means the repo has auto-merge enabled and may use merge queues. -If `--auto` is not available (repo doesn't have auto-merge enabled), merge directly: +`--auto` fails for two unrelated reasons. Both fall through to the direct merge below, so +the flow is unaffected — but do not report the second one as "auto-merge is disabled": + +1. **Auto-merge is disabled for the repo** — `Auto-merge is not allowed for this repository`. +2. **The PR is not waiting on anything.** `--auto` only *queues* a merge behind pending + required checks. When every required check has already settled — or the repo declares + no required status checks at all — GitHub treats the PR as immediately mergeable and + rejects the mutation: + `Pull request is in clean status` (everything green) or + `Pull request is in unstable status` (something red, but nothing required). + A repo with zero required status checks therefore takes the direct path 100% of the + time no matter how auto-merge is configured, and so does any repo whose CI finishes + before this step runs. ```bash gh pr merge --squash --delete-branch