Merge Conflicts

Merge Conflicts is the repository-scoped workflow Polygent uses when delivering work hits conflicting changes: it merges the branches, lets AI propose resolutions, and has a person review the result before it is pushed.

When a merge request is created

Merge requests are created automatically; there is no manual start.

Trigger	Branches merged
A ticket's merge or pull-request stage reports conflicts	The ticket branch and its starting branch, per repository. When the ticket has a pull request, the resolution is pushed to the pull request's source branch.
Merge to Starter in a session hits conflicts	The session branch and its starting branch.
Creating a session pull request fails because of conflicts	The session branch and the target branch.

One merge request is active per repository and ticket (or per repository and source branch when no ticket is involved); a repeated trigger returns the existing request instead of creating a duplicate. Different tickets can resolve conflicts in the same repository concurrently. Both branches must exist on the remote and a session host must be available.

If Git merges cleanly, Polygent commits and pushes the result without opening the conflict editor.

Before relying on it

A merge writes commits and pushes a branch, so verify access and repository protection first.

• The workspace credential must be able to fetch and push the affected branch. For pull-request merges, the source branch must accept pushes.
• Viewing requires View Merge Conflicts; resolving, retrying, skipping AI, and canceling require Manage Merge Conflicts.
• AI resolution is configured under Management → System → Merge Conflicts: Manual Merge Conflicts (off by default) skips AI entirely, AI Conflict Resolver selects the model, and Tools limits its capabilities.
• Each AI attempt is limited to 30 minutes by default (MergeAiTimeoutSeconds); time waiting for capacity and running merge hooks does not count. AI runs are limited per session host by Max Concurrent Merge AI Processes (default 2); extra requests wait with a visible queued state.
• Keep automatic acceptance off unless the workspace trusts its validation hooks, branch protections, and AI resolutions.

Resolve conflicted files

Resolution is human-reviewed by default.

1. Open the merge request from the ticket, session, or My Work item. Assigned developers see tickets needing conflict review in My Work.
2. Wait for the AI attempt, or select Skip AI & Resolve Manually.
3. Open every file under Conflict Files in the diff editor; it compares the starting branch with the resolved content.
4. Edit the resolved side to the required final content.
5. Select Resolve & Push. It stays disabled until every conflicted file has been opened ("Review all files before resolving").
6. Confirm the push succeeded, then run the repository's normal build, test, and security checks.

Only conflicted files are listed; files Git merged on its own need no action. Binary files cannot be edited in the browser — resolve binary conflicts in Git directly and retry. Before pushing, Polygent fetches the branches again; if the destination moved and new conflicts appear, the request returns to review with those files.

Automatic acceptance

Automatic acceptance lets trusted workspaces complete validated AI resolutions without waiting for Resolve & Push.

1. Open the workspace Tickets tab.
2. Enable Auto Accept Merge Conflict Resolution and save. It is off by default.

When enabled, Polygent commits, rechecks the remote branch, pushes, runs completion hooks, and completes the merge only after AI resolution succeeds, no conflict markers remain, and validation hooks pass. Pull-request resolutions update the source branch, preserving the provider's own approval flow. Processing and successfully auto-accepted merges are not shown as actionable in the sidebar. Timeouts, remaining markers, failed hooks, provider failures, new conflicts, and push failures keep the conflict workspace and show the ticket for retry or manual resolution. With Manual Merge Conflicts on, every merge still requires review.

Hooks and validation

Merge requests run the workspace's session hooks when the merge workspace is created, after the AI attempt, on completion, and on cancellation.

Use hooks for non-interactive validation such as dependency checks or a test suite. A hook is not a substitute for branch protection or pull-request checks; keep required checks enforced by the Git provider. See Session Hooks.

Retry and recovery

A failed AI attempt keeps the merge request open and its conflict workspace intact.

• Retry runs AI again on the same request after refreshing the branches from the remote.
• Manual Resolve continues in the preserved conflict workspace without refreshing.
• The reason for the failure — timeout, conflict markers remaining, hook failure, validation failure, or provider error — is shown on the request and in the ticket details.
• AI cost from every attempt is recorded as the ticket's Merge Cost.

Cancel safely

Cancel Merge opens a confirmation warning that current resolution work will be lost. Confirming stops AI work, removes the temporary merge workspace, and marks the request canceled. It does not undo commits already pushed; revert those through your normal Git process.

Troubleshooting

The merge status and system logs identify whether a failure occurred during repository access, resolution, validation, commit, or push.

Symptom	Resolution
Merge request stays queued	Session hosts are at Max Concurrent Merge AI Processes; wait or raise the limit on the Hosts page.
Resolve & Push is disabled	Open every file in Conflict Files.
Fetch or clone fails	Verify repository URL, DNS/TLS reachability, credentials, and read access from the session host; the system logs show the Git error.
Merge setup fails	Polygent retries a transient network or Git lock failure once. Correct the reported revision, credential, permission, or lock issue, then retry. Do not delete shared repository storage.
Push is denied	Grant the credential push access or adjust branch protection; prefer pushing to the pull-request source branch when direct target updates are prohibited.
AI attempt fails or times out	Correct the reported issue and use Retry, or select Manual Resolve.
A binary file conflicts	Resolve it in Git outside Polygent, push, and retry the request.
New conflicts appear after AI	The destination branch advanced; Retry rebuilds from the current branches, or resolve the new files manually.
Service stopped during a merge	After restart, check the request status; interrupted merge workspaces are cleaned up automatically. Retry or wait for the next trigger.

Never paste repository credentials into conflict content or messages. Rotate the credential if a secret is exposed in a branch, log, or generated resolution.