bugfix-314-error-merging-release-branch-after-successful-deployment: Enhance documentation and implementation for deploy label and merge flow. Added new sections in README and index.mdx, and improved MergeRepository to wait for PR-specific check runs before merging. Updated tests for MergeRepository and DeployedActionUseCase to cover new behavior and ensure correctness in handling merges and check waits.

efraespada · efraespada · commit e752467e6f78 · 2026-02-15T16:40:19.000+01:00
diff --git a/README.md b/README.md
@@ -23,6 +23,7 @@ Full documentation: **[docs.page/vypdev/copilot](https://docs.page/vypdev/copilo
 | [OpenCode (AI)](https://docs.page/vypdev/copilot/opencode-integration) | Progress, Bugbot, think, AI PR description |
 | [Testing OpenCode locally](https://docs.page/vypdev/copilot/testing-opencode-plan-locally) | Run check-progress, detect-potential-problems, recommend-steps via CLI |
 | [Single actions](https://docs.page/vypdev/copilot/single-actions) | On-demand: check progress, think, create release/tag, deployed |
+| [Deploy label and merge flow](docs/single-actions/deploy-label-and-merge.mdx) | Deploy/deployed labels, post-deploy merges, waiting for checks per PR |
 | [Issues](https://docs.page/vypdev/copilot/issues) | Issue configuration and types (feature, bugfix, hotfix, release, docs, chore) |
 | [Pull requests](https://docs.page/vypdev/copilot/pull-requests) | PR configuration and AI description |
 | [Troubleshooting](https://docs.page/vypdev/copilot/troubleshooting) | Common issues and solutions |
diff --git a/docs/single-actions/deploy-label-and-merge.mdx b/docs/single-actions/deploy-label-and-merge.mdx
@@ -0,0 +1,69 @@
+---
+title: Deploy label and merge flow
+description: How the deploy and deployed labels work and how post-deploy merges and check runs are handled.
+---
+
+# Deploy label and merge flow
+
+This page describes how the **deploy** label is used and what happens when you run the **deployed** single action after a successful deployment. It also explains how branch merges and check runs are handled so that both release→default and release→develop (or hotfix equivalents) complete correctly.
+
+## The deploy label
+
+- **`deploy`** — Applied to the issue when the release (or hotfix) is ready to be deployed. Your CI/CD or team adds this label when deployment has been triggered or is about to be.
+- **`deployed`** — Set by Copilot when the **deployed** single action runs and the issue had the **deploy** label. It indicates "deployment is done and post-deploy steps have been run."
+
+The **deployed** single action is intended to be run **after a successful deployment** (e.g. from a pipeline step or a manual trigger). It requires:
+
+- An issue number (single action is run with `single-action-issue: <number>`).
+- The issue must have the **deploy** label and must **not** already have the **deployed** label.
+
+## What the deployed action does
+
+1. **Label update**  
+   Replaces the **deploy** label with **deployed** on the issue.
+
+2. **Branch merges** (if a release or hotfix branch is configured):
+   - **Release:** merges the release branch into the default branch (e.g. `main`), then into the development branch (e.g. `develop`).
+   - **Hotfix:** merges the hotfix branch into the default branch, then merges the default branch into the development branch.
+
+3. **Issue closure**  
+   If **all** merge operations succeed, the issue is closed. If any merge fails, the issue is left open and the action reports that one or more merge operations failed.
+
+Each merge is done via a **pull request**: create PR, wait for checks (see below), then merge the PR. If the PR workflow fails (e.g. checks fail or timeout), the code falls back to a **direct** Git merge when possible.
+
+## Waiting for checks before merging
+
+For each PR we create (e.g. release→main, release→develop), we wait until the PR is ready to merge before calling the merge API.
+
+### Per-PR check runs
+
+- GitHub's Checks API returns check runs **by ref** (branch), not by PR. The same branch can be the head of **multiple PRs** (e.g. release→main and release→develop).
+- We **only consider check runs that belong to the current PR**, using the `pull_requests` array on each check run (filter by `pull_request.number === this PR`). We do **not** use check runs from another PR (e.g. the first merge) to decide that the second PR is ready.
+- We wait until all check runs for **this** PR are completed and none have failed. Only then do we merge.
+
+### When the PR has no check runs
+
+- If there are **no** check runs on the ref, we use **commit status checks** (legacy) and merge when none are pending.
+- If there **are** check runs on the ref but **none** for this PR (e.g. they are from another PR with the same head, or this base branch has no required checks), we wait a short number of polls (~30 seconds). If no check runs appear for this PR in that window, we assume this PR does not require check runs and **proceed to merge**. If the branch actually requires checks, GitHub will reject the merge and we fall back to the direct merge path (which may also fail under branch protection).
+
+### Timeout
+
+- A configurable **merge timeout** (input `merge-timeout`, default 600 seconds) limits how long we wait for checks **per merge**. If we hit the timeout, we throw and the code attempts a direct merge as fallback.
+
+## Summary table
+
+| Scenario | Behaviour |
+|----------|-----------|
+| PR has check runs for this PR | Wait until all are completed and none failed, then merge. |
+| PR has no check runs on ref | Use status checks; if none pending, merge. |
+| Check runs on ref but none for this PR | Wait a few polls (~30 s); if still none, proceed to merge (branch may have no required checks). |
+| Timeout waiting for checks | Attempt direct merge. |
+| PR merge fails, direct merge fails | Return failure; issue is not closed. |
+
+## Related code and tests
+
+- **Use case:** `src/usecase/actions/deployed_action_use_case.ts` — deploy label handling, merge order, issue close.
+- **Merge and checks:** `src/data/repository/merge_repository.ts` — PR creation, per-PR check filtering, status checks fallback, direct merge fallback.
+- **Tests:**
+  - `src/usecase/actions/__tests__/deployed_action_use_case.test.ts` — deploy label validation, release/hotfix merge order, close on success, no close on merge failure.
+  - `src/data/repository/__tests__/merge_repository.test.ts` — check runs per PR, no check runs, timeout, direct merge fallback.
diff --git a/docs/single-actions/index.mdx b/docs/single-actions/index.mdx
@@ -14,6 +14,9 @@ When you set the **`single-action`** input (and any required targets such as `si
   <Card title="Configuration" icon="gear" href="/single-actions/configuration">
     single-action, single-action-issue, single-action-version, and other inputs.
   </Card>
+  <Card title="Deploy label and merge flow" icon="git-merge" href="/single-actions/deploy-label-and-merge">
+    Deploy/deployed labels, post-deploy merges (release/hotfix → default and develop), and how we wait for checks per PR.
+  </Card>
   <Card title="Workflow & CLI" icon="terminal" href="/single-actions/workflow-and-cli">
     Run from a GitHub Actions workflow or from the giik CLI.
   </Card>
@@ -38,5 +41,6 @@ When you set the **`single-action`** input (and any required targets such as `si
 ## Next steps
 
 - **[Available actions](/single-actions/available-actions)** — Complete list with inputs and descriptions.
+- **[Deploy label and merge flow](/single-actions/deploy-label-and-merge)** — Deploy/deployed labels and post-deploy merges.
 - **[Workflow & CLI](/single-actions/workflow-and-cli)** — How to run from a workflow and from the CLI.
 - **[Examples](/single-actions/examples)** — YAML and CLI examples.
diff --git a/src/data/repository/__tests__/merge_repository.test.ts b/src/data/repository/__tests__/merge_repository.test.ts
@@ -1,5 +1,8 @@
 /**
- * Unit tests for MergeRepository: mergeBranch (PR merge and direct merge fallback).
+ * Unit tests for MergeRepository.mergeBranch: PR creation, waiting for checks per PR,
+ * fallback when the PR has no check runs, timeout, and direct merge fallback.
+ *
+ * Used by the deploy flow (release/hotfix → default and develop). See docs/single-actions/deploy-label-and-merge.mdx.
  */
 
 import { MergeRepository } from '../merge_repository';
@@ -50,6 +53,7 @@ describe('MergeRepository', () => {
         mockReposGetCombinedStatusForRef.mockReset();
     });
 
+    describe('PR creation and merge (timeout <= 10 skips waiting for checks)', () => {
     it('creates PR, updates body, merges and returns success (timeout <= 10 skips wait)', async () => {
         mockPullsCreate.mockResolvedValue({
             data: { number: 42 },
@@ -136,7 +140,9 @@ describe('MergeRepository', () => {
         expect(result.some(r => r.success === false && r.steps?.some(s => s.includes('Failed to merge')))).toBe(true);
         expect(result.length).toBeGreaterThanOrEqual(2);
     });
+    });
 
+    describe('waiting for checks (timeout > 10): per-PR check runs, no checks, timeout', () => {
     it('when timeout > 10 waits for check runs (all completed) then merges', async () => {
         mockPullsCreate.mockResolvedValue({ data: { number: 1 } });
         mockPullsListCommits.mockResolvedValue({ data: [{ commit: { message: 'msg' } }] });
@@ -145,7 +151,7 @@ describe('MergeRepository', () => {
         mockChecksListForRef.mockResolvedValue({
             data: {
                 check_runs: [
-                    { name: 'ci', status: 'completed', conclusion: 'success' },
+                    { name: 'ci', status: 'completed', conclusion: 'success', pull_requests: [{ number: 1 }] },
                 ],
             },
         });
@@ -179,7 +185,7 @@ describe('MergeRepository', () => {
         mockChecksListForRef.mockResolvedValue({
             data: {
                 check_runs: [
-                    { name: 'ci', status: 'completed', conclusion: 'failure' },
+                    { name: 'ci', status: 'completed', conclusion: 'failure', pull_requests: [{ number: 1 }] },
                 ],
             },
         });
@@ -214,14 +220,87 @@ describe('MergeRepository', () => {
         expect(mockReposGetCombinedStatusForRef).toHaveBeenCalled();
     });
 
+    it('when timeout > 10 waits only for check runs tied to this PR (ignores runs from other PRs with same head)', async () => {
+        jest.useFakeTimers();
+        mockPullsCreate.mockResolvedValue({ data: { number: 42 } });
+        mockPullsListCommits.mockResolvedValue({ data: [{ commit: { message: 'msg' } }] });
+        mockPullsUpdate.mockResolvedValue({});
+        mockPullsMerge.mockResolvedValue({});
+        // First poll: runs exist but for another PR (e.g. release→master already merged). We must not treat as completed.
+        mockChecksListForRef
+            .mockResolvedValueOnce({
+                data: {
+                    check_runs: [
+                        { name: 'ci', status: 'completed', conclusion: 'success', pull_requests: [{ number: 1 }] },
+                    ],
+                },
+            })
+            .mockResolvedValueOnce({
+                data: {
+                    check_runs: [
+                        { name: 'ci', status: 'completed', conclusion: 'success', pull_requests: [{ number: 42 }] },
+                    ],
+                },
+            });
+        mockReposGetCombinedStatusForRef.mockResolvedValue({
+            data: { state: 'success', statuses: [] },
+        });
+
+        const promise = repo.mergeBranch(
+            'owner',
+            'repo',
+            'release/1.0',
+            'develop',
+            30,
+            'token',
+        );
+        await jest.runAllTimersAsync();
+        const result = await promise;
+
+        jest.useRealTimers();
+        expect(result).toHaveLength(1);
+        expect(result[0].success).toBe(true);
+        expect(mockChecksListForRef).toHaveBeenCalledTimes(2);
+        expect(mockPullsMerge).toHaveBeenCalled();
+    });
+
+    it('when timeout > 10 and no check runs for this PR after a few polls, proceeds to merge (branch may have no required checks)', async () => {
+        jest.useFakeTimers();
+        mockPullsCreate.mockResolvedValue({ data: { number: 99 } });
+        mockPullsListCommits.mockResolvedValue({ data: [] });
+        mockPullsUpdate.mockResolvedValue({});
+        mockPullsMerge.mockResolvedValue({});
+        // Check runs on ref are for another PR only; this PR (99) has none (e.g. develop has no required checks).
+        mockChecksListForRef.mockResolvedValue({
+            data: {
+                check_runs: [
+                    { name: 'ci', status: 'completed', conclusion: 'success', pull_requests: [{ number: 1 }] },
+                ],
+            },
+        });
+        mockReposGetCombinedStatusForRef.mockResolvedValue({
+            data: { state: 'success', statuses: [] },
+        });
+
+        const promise = repo.mergeBranch('o', 'r', 'release/1.0', 'develop', 60, 'token');
+        await jest.runAllTimersAsync();
+        const result = await promise;
+
+        jest.useRealTimers();
+        expect(result).toHaveLength(1);
+        expect(result[0].success).toBe(true);
+        expect(mockChecksListForRef).toHaveBeenCalledTimes(3);
+        expect(mockPullsMerge).toHaveBeenCalled();
+    });
+
     it('when timeout > 10 and checks never complete throws then direct merge succeeds', async () => {
         jest.useFakeTimers();
         mockPullsCreate.mockResolvedValue({ data: { number: 1 } });
         mockPullsListCommits.mockResolvedValue({ data: [] });
         mockPullsUpdate.mockResolvedValue({});
         mockChecksListForRef.mockResolvedValue({
             data: {
-                check_runs: [{ name: 'ci', status: 'in_progress', conclusion: null }],
+                check_runs: [{ name: 'ci', status: 'in_progress', conclusion: null, pull_requests: [{ number: 1 }] }],
             },
         });
         mockReposGetCombinedStatusForRef.mockResolvedValue({
@@ -236,4 +315,5 @@ describe('MergeRepository', () => {
         jest.useRealTimers();
         expect(result.some(r => r.success === true && r.steps?.some(s => s.includes('direct merge')))).toBe(true);
     });
+    });
 });
diff --git a/src/data/repository/merge_repository.ts b/src/data/repository/merge_repository.ts
@@ -3,8 +3,14 @@ import { logDebugInfo, logError } from '../../utils/logger';
 import { Result } from '../model/result';
 
 /**
- * Repository for merging branches (via PR or direct merge).
- * Isolated to allow unit tests with mocked Octokit.
+ * Repository for merging branches: creates a PR, waits for that PR's check runs (or status checks),
+ * then merges the PR; on failure, falls back to a direct Git merge.
+ *
+ * Check runs are filtered by PR (pull_requests) so we only wait for the current PR's checks,
+ * not those of another PR sharing the same head (e.g. release→main vs release→develop).
+ * If the PR has no check runs after a short wait, we proceed to merge (branch may have no required checks).
+ *
+ * @see docs/single-actions/deploy-label-and-merge.mdx for the deploy flow and check-wait behaviour.
  */
 export class MergeRepository {
 
@@ -61,10 +67,13 @@ This PR merges **${head}** into **${base}**.
             });
 
             const iteration = 10;
+            /** Give workflows a short window to register check runs for this PR; after this, we allow merge with no check runs (e.g. branch has no required checks). */
+            const maxWaitForPrChecksAttempts = 3;
             if (timeout > iteration) {
                 // Wait for checks to complete - can use regular token for reading checks
                 let checksCompleted = false;
                 let attempts = 0;
+                let waitForPrChecksAttempts = 0;
                 const maxAttempts = timeout > iteration ? Math.floor(timeout / iteration) : iteration;
 
                 while (!checksCompleted && attempts < maxAttempts) {
@@ -74,6 +83,14 @@ This PR merges **${head}** into **${base}**.
                         ref: head,
                     });
 
+                    // Only consider check runs that are for this PR. When the same branch is used in
+                    // multiple PRs (e.g. release→master and release→develop), listForRef returns runs
+                    // for all PRs; we must wait for runs tied to the current PR or we may see completed
+                    // runs from the other PR and merge before this PR's checks have run.
+                    const runsForThisPr = (checkRuns.check_runs as Array<{ status: string; conclusion: string | null; name: string; pull_requests?: Array<{ number: number }> }>).filter(
+                        run => run.pull_requests?.some(pr => pr.number === pullRequest.number),
+                    );
+
                     // Get commit status checks for the PR head commit
                     const { data: commitStatus } = await octokit.rest.repos.getCombinedStatusForRef({
                         owner: owner,
@@ -82,11 +99,11 @@ This PR merges **${head}** into **${base}**.
                     });
 
                     logDebugInfo(`Combined status state: ${commitStatus.state}`);
-                    logDebugInfo(`Number of check runs: ${checkRuns.check_runs.length}`);
+                    logDebugInfo(`Number of check runs for this PR: ${runsForThisPr.length} (total on ref: ${checkRuns.check_runs.length})`);
 
-                    // If there are check runs, prioritize those over status checks
-                    if (checkRuns.check_runs.length > 0) {
-                        const pendingCheckRuns = checkRuns.check_runs.filter(
+                    // If there are check runs for this PR, wait for them to complete
+                    if (runsForThisPr.length > 0) {
+                        const pendingCheckRuns = runsForThisPr.filter(
                             check => check.status !== 'completed',
                         );
 
@@ -95,7 +112,7 @@ This PR merges **${head}** into **${base}**.
                             logDebugInfo('All check runs have completed.');
 
                             // Verify if all checks passed
-                            const failedChecks = checkRuns.check_runs.filter(
+                            const failedChecks = runsForThisPr.filter(
                                 check => check.conclusion === 'failure',
                             );
 
@@ -111,6 +128,21 @@ This PR merges **${head}** into **${base}**.
                             attempts++;
                             continue;
                         }
+                    } else if (checkRuns.check_runs.length > 0 && runsForThisPr.length === 0) {
+                        // There are runs on the ref but none for this PR. Either workflows for this PR
+                        // haven't registered yet, or this PR/base has no required checks.
+                        waitForPrChecksAttempts++;
+                        if (waitForPrChecksAttempts >= maxWaitForPrChecksAttempts) {
+                            checksCompleted = true;
+                            logDebugInfo(
+                                `No check runs for this PR after ${maxWaitForPrChecksAttempts} polls; proceeding to merge (branch may have no required checks).`,
+                            );
+                        } else {
+                            logDebugInfo('Check runs exist on ref but none for this PR yet; waiting for workflows to register.');
+                            await new Promise(resolve => setTimeout(resolve, iteration * 1000));
+                            attempts++;
+                        }
+                        continue;
                     } else {
                         // Fall back to status checks if no check runs exist
                         const pendingChecks = commitStatus.statuses.filter(status => {
diff --git a/src/usecase/actions/__tests__/deployed_action_use_case.test.ts b/src/usecase/actions/__tests__/deployed_action_use_case.test.ts
diff --git a/src/usecase/actions/deployed_action_use_case.ts b/src/usecase/actions/deployed_action_use_case.ts
