From 7630d10684e7ca51205aca2119343f97277e66d2 Mon Sep 17 00:00:00 2001
From: ryz310 <ryz310@gmail.com>
Date: Tue, 24 Feb 2026 20:51:03 +0900
Subject: [PATCH] Add runbook for Dependabot PR auto-merge workflow

---
 AGENTS.md                                 |  3 +
 docs/runbooks/dependabot_pr_auto_merge.md | 68 +++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 docs/runbooks/dependabot_pr_auto_merge.md

diff --git a/AGENTS.md b/AGENTS.md
index 661b06fe..5faed6c9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -76,3 +76,6 @@
 - Propose a KPT retrospective when a task reaches a completion point, such as after creating a Pull Request.
 - Based on the KPT results, propose updates to `AGENTS.md`.
 - The timing of the retrospective may be decided by Codex when it is appropriate.
+
+## Runbook
+- Dependabot PR review and auto-merge operation steps are documented in `docs/runbooks/dependabot_pr_auto_merge.md`.
diff --git a/docs/runbooks/dependabot_pr_auto_merge.md b/docs/runbooks/dependabot_pr_auto_merge.md
new file mode 100644
index 00000000..d8cf19ab
--- /dev/null
+++ b/docs/runbooks/dependabot_pr_auto_merge.md
@@ -0,0 +1,68 @@
+# Dependabot PR Review and Auto-Merge Runbook
+
+## Purpose
+This runbook standardizes how to review Dependabot pull requests for GitHub Actions updates and safely enable auto-merge.
+
+## Scope
+- Target: Dependabot PRs that update GitHub Actions versions (for example, `actions/upload-artifact`).
+- Primary workflow file in this repository: `.github/workflows/ci.yml`.
+
+## Prerequisites
+- `gh` CLI is authenticated and can access `ryz310/my_api_client`.
+- You have permission to comment on and merge PRs.
+- Branch protection rules and required checks are configured on GitHub.
+
+## Step-by-step
+1. Open PR metadata and changed files.
+
+```bash
+gh pr view <PR_NUMBER> --json number,title,author,baseRefName,headRefName,files,body
+```
+
+2. Review the exact diff and identify action version changes.
+
+```bash
+gh pr diff <PR_NUMBER>
+```
+
+3. Compare old and new action versions and summarize impact.
+- Focus on major version changes and runtime requirements (Node version, runner minimum version, breaking changes).
+- For `actions/upload-artifact`, verify compatibility notes in the official release notes.
+
+4. Enable auto-merge with squash merge.
+
+```bash
+gh pr merge <PR_NUMBER> --auto --squash
+```
+
+5. Check merge state.
+
+```bash
+gh pr view <PR_NUMBER> --json state,mergeStateStatus,autoMergeRequest
+```
+
+6. If state is `BEHIND`, request Dependabot rebase.
+
+```bash
+gh pr comment <PR_NUMBER> --body "@dependabot rebase"
+```
+
+7. Re-check status until the branch is up to date and required checks pass.
+
+```bash
+gh pr view <PR_NUMBER> --json state,mergeStateStatus,statusCheckRollup,autoMergeRequest
+```
+
+## Done criteria
+- `autoMergeRequest` is enabled.
+- `mergeStateStatus` is not `BEHIND`.
+- Required CI checks are green.
+- PR is merged automatically, or clearly waiting only on pending required checks.
+
+## Failure handling
+- If rebase does not start, re-run comment:
+  - `@dependabot rebase`
+- If checks fail, inspect failing jobs and decide:
+  - fix in a follow-up PR, or
+  - close/ignore that update version with Dependabot commands.
+- If the update introduces breaking changes, disable auto-merge and switch to manual review with explicit test evidence.