Carlos Florêncio
80 lines
2.7 KiB
Markdown
80 lines
2.7 KiB
Markdown
---
|
|
created: 2026-08-28
|
|
status: done
|
|
requirements:
|
|
- REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001
|
|
system_design:
|
|
- ../../specs/integrations/system-design/github-pr-merge-queue.md
|
|
legacy_specs: []
|
|
---
|
|
|
|
# Implementation Plan: GitHub Async Merge Response Contract Fix
|
|
|
|
## Overview
|
|
|
|
Correct both GitHub clients to decode the documented asynchronous merge
|
|
response. Add provider-boundary tests before the production correction.
|
|
|
|
## Scope
|
|
|
|
### In scope
|
|
|
|
- Decode `details.uuid` from pending asynchronous merge responses.
|
|
- Decode `details.message` from failed asynchronous merge responses.
|
|
- Poll accepted and existing merge requests through both GitHub clients.
|
|
- Replace flat response fixtures with the documented nested response shape.
|
|
|
|
### Out of scope
|
|
|
|
- Changes to merge eligibility or automation policy.
|
|
- Changes to merge-queue observation or persistence.
|
|
- UI, localization, database, and public documentation changes.
|
|
- Automatic merge retries after a terminal GitHub failure.
|
|
|
|
## Technical approach
|
|
|
|
Update `mergeAsyncResponse` in `apps/backend/internal/github/client.go`. Model
|
|
the provider `details` object with its UUID and message fields.
|
|
|
|
Update `GHClient.MergePR` and `PATClient.MergePR` to read the nested fields.
|
|
Keep the existing status normalization and the `gh` conflict-body extraction.
|
|
|
|
Add real response shapes to `gh_client_commands_test.go` and
|
|
`pat_client_writes_test.go`. Each client test first receives a nested pending
|
|
response. It then polls the UUID and receives a terminal result.
|
|
|
|
## Tests
|
|
|
|
- `AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.3`: Both clients poll
|
|
`details.uuid` and return the final merged or queued outcome.
|
|
- `AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.13`: Both clients report
|
|
`details.message` for a terminal failed result.
|
|
- The `gh` client keeps its embedded JSON extraction for a `409` response.
|
|
|
|
## E2E tests
|
|
|
|
No new Playwright test is required. Existing merge-action and CI automation
|
|
tests cover normalized outcomes. This fix changes the external provider
|
|
decoder below the mock-provider boundary.
|
|
|
|
## Work orders
|
|
|
|
- [x] [Task 01: Decode async merge details](task-01-decode-async-merge-details.md)
|
|
|
|
## Verification results
|
|
|
|
- The RED test run failed all six nested-response cases for the expected
|
|
missing UUID and message behavior.
|
|
- `go test -tags fts5 ./internal/github -run 'Test(GHClient|PATClient)_MergePR'`
|
|
passed 21 tests.
|
|
- `python3 scripts/lint-spec-files.py --all` passed.
|
|
- `git diff --check` passed.
|
|
- The targeted `gofmt -l` command returned no files.
|
|
|
|
## Risks
|
|
|
|
- The `gh` client receives a `409` body inside CLI error text. The correction
|
|
must preserve the existing JSON extraction.
|
|
- Both clients share the response model. A partial correction can leave one
|
|
authentication route broken.
|