From Code Generation to Merge: A Guide to the Review & Merge Workflow

You’ve defined your outcome, and the AI agent has worked its magic, turning your prompt into a tangible set of code changes. Now what? The final step in the development lifecycle is to review, verify, and merge that work into your main codebase. This guide will walk you through the powerful "Review & Merge" workflow in the Task Workspace, helping you understand when to use each feature and how it all ties into the sandbox environment.

The Pull Request: Your Gateway to Production

A Pull Request (PR) is the formal proposal to merge the code generated by a task into your main branch. While the AI agent will often create a PR for you automatically upon completing a task, you always have the control to create one manually from the Task Actions menu in the header.

Once a PR is created, the workspace comes alive with new information:

PR Status & Link: The header will display the PR's status (open, closed, or merged) and provide a direct link to it on GitHub.
Checks: This is where your existing CI/CD pipeline comes into play. The application will display the status of any configured GitHub Actions or other status checks, giving you immediate feedback on whether the new code meets your quality gates (e.g., tests passing, linting rules met). If a check fails, you can use the Chat Pane to instruct the agent to fix the issue.

Choosing Your Merge Strategy

When you’re confident the changes are ready, clicking the "Merge" button will present you with several options. Choosing the right one depends on your team's workflow and how you prefer to manage your Git history.

1. Squash and Merge

What it is: This option combines all of the PR's individual commits into a single, clean commit on the main branch.
When to use it: This is the most common and generally recommended approach. It keeps your main branch history clean and easy to read. Each commit on the main branch represents a complete feature or fix, making it simple to track changes and revert them if necessary.
Scenario: Imagine a task where the agent made 5 commits to fix a bug. "Squash and Merge" will condense those into one commit, like "fix: resolve user authentication issue," keeping your git log tidy.

2. Create a Merge Commit

What it is: This method preserves all of the individual commits from the PR's branch and adds them to the main branch, enclosed in a single merge commit.
When to use it: Use this when you want to retain the detailed commit history of a feature branch. This can be useful for complex features where you want to see the step-by-step development process.
Scenario: For a large feature that took several days and multiple commits to develop, you might want to preserve that history for future reference. A merge commit will show the entire journey of the feature's creation.

3. Rebase and Merge

What it is: This option takes all the commits from the PR and re-applies them individually onto the main branch.
When to use it: "Rebase and Merge" creates the cleanest possible Git history, showing a single, linear progression of commits. However, it rewrites history, which can be problematic for shared branches. This is best used by developers who are very comfortable with Git and have a specific history management strategy.
Scenario: If you want your project history to look as if the work was done in a straight line without any branching, rebasing is the way to go.

The Sandbox Lifecycle and Merging

The sandbox is the isolated environment where the agent works. Understanding its lifecycle is key to a smooth workflow.

The 5-Minute Reminder: If a task has the keepAlive option enabled, the sandbox will remain active after the initial work is done. However, to conserve resources, it will automatically shut down after a period of inactivity. You'll receive a warning when there are about 5 minutes remaining. This is your cue to either finish your review and merge, or to use the Chat Pane to give the agent another instruction to keep the sandbox active.
When to Create a PR: You can create a PR at any time. If the agent has completed its work, it's a good time to create one. If you want to create a PR mid-task to get feedback, you can do that too. The sandbox will remain active (if keepAlive is on) while you review the PR.

AI-Powered Conflict Resolution

What happens if another change was merged to the main branch while your task was running, creating a merge conflict? The application has you covered.

When a merge conflict is detected, a dialog will appear, giving you the option to have an AI agent attempt to resolve the conflicts. The agent will analyze the conflicting code, merge the changes intelligently, and push a new commit with the resolved conflicts, saving you the manual effort.

By mastering the "Review & Merge" workflow, you can confidently and efficiently integrate AI-generated code into your projects, maintaining a high level of quality and a clean, manageable codebase.