# Merge proposals ## Overview A merge proposal records a request to merge one [branch’s](/guides/elevenagents-operate-versioning#branches) changes into another and lets a teammate review the diff before that happens. Anyone with edit access to the agent can open a proposal, even into a branch they cannot merge into themselves. Merging the proposal still requires write access to the target branch, so a proposal is how a change reaches a protected branch without giving every contributor merge rights on it. :::callout{intent="note"} Merge proposals add an optional review step on top of [merging branches directly](/guides/elevenagents-operate-versioning#merging-branches). Merge directly when you have write access to the target branch and don’t need a second opinion. Open a proposal when you want one reviewed first, or when the target branch is protected and you don’t have write access to it. ::: ## Availability Merge proposals are in alpha. When several branches of an agent are in progress at once, it becomes hard to track which ones are ready and safe to merge. Merge proposals give a team one place to review and discuss a branch’s changes, compare test pass rates between branches, and look at the branch’s latest conversations. The alpha is a first step toward a CI/CD-style workflow for agents, similar to pull requests on GitHub. Planned additions over the coming weeks include: - Required tests that must pass before a proposal can be merged. - Requesting approvals from specific reviewers. - Configuring owners for different parts of an agent. ## Proposal lifecycle Every proposal has one of these statuses: | Status | Meaning | | ------ | ------------------------------------------------------------------------------------------------------------------ | | Open | Waiting for review or merge. | | Merged | The source branch’s changes were merged into the target branch. | | Closed | Withdrawn by the author, rejected by someone else, or closed automatically because the source branch was archived. | While a proposal is open, reviewers leave one of these verdicts. A reviewer’s latest verdict replaces any earlier one from that same reviewer: | Review state | Meaning | | ----------------- | ----------------------------------------------------------------- | | Approved | The reviewer is satisfied with the changes. | | Changes requested | The reviewer wants something addressed before this can be merged. | ## Opening a proposal Open a proposal from the branch whose changes you want reviewed: ::::tabs :::tab{title="From the branch list"} In the agent’s **Branches** tab, open the options menu on the source branch and select **Open merge proposal**. Open merge proposal option in a branch's options menu ::: :::tab{title="From the Proposals tab"} In the agent's **Branches > Proposals** tab, select the source branch, then click **Create proposal**. Proposals tab on an agent's Branches page Give the proposal a title, an optional description, and pick a target branch from the agent's other non-archived branches. Opening a proposal does not change either branch; it only records the request. A source and target branch pair can have at most one open proposal at a time. Close the existing one before opening another between the same two branches. ::: :::: Give the proposal a title, an optional description, and pick a target branch from the agent’s other non-archived branches. Opening a proposal does not change either branch; it only records the request. :::callout{intent="note"} A source and target branch pair can have at most one open proposal at a time. Close the existing one before opening another between the same two branches. ::: ## Reviewing a proposal A proposal’s page has these tabs: ::::tabs :::tab{title="Overview"} The description, review history, and a form for leaving a review. Overview tab of a merge proposal ::: :::tab{title="Changes"} A diff between the source and target branch configurations. Changes tab of a merge proposal ::: :::tab{title="Test runs"} The source branch's test history, so reviewers can check it still passes before approving. Test runs tab of a merge proposal ::: :::tab{title="Conversations"} Recent conversations on the source branch. Conversations tab of a merge proposal Anyone with edit access to the agent, other than the proposal's own author, can leave a review with an optional comment. Comments support markdown. ::: :::: Anyone with edit access to the agent, other than the proposal’s own author, can leave a review with an optional comment. Comments support markdown. ## Merging a proposal Merging a proposal performs the same [branch merge](/guides/elevenagents-operate-versioning#merging-branches) as merging directly, including [conflict resolution](/guides/elevenagents-operate-versioning#resolving-merge-conflicts) and the option to archive the source branch afterward. Before it can be merged, a proposal must meet these requirements: - The merging user has write access to both the source and target branches. On a [protected branch](/guides/elevenagents-operate-versioning), that means being a workspace admin. - No reviewer’s latest verdict is “changes requested”. A reviewer who requested changes must approve before the proposal can be merged. - The proposal has at least one approval from someone other than its author. Workspace admins can merge without this approval. Merging a proposal automatically closes any other open proposal for the same source branch, since its changes have now moved on. ## Closing a proposal A proposal can be closed without merging at any point while it’s open. The author and reviewers can edit its title and description up until it’s closed. - The author closing their own proposal records it as **withdrawn**. - Anyone else closing it records it as **rejected**. - Archiving the source branch closes any open proposal from or to it automatically, recorded as **branch\_archived**. ## Merge proposals and Architect [Architect](/guides/elevenagents-operate-architect) has read access to an agent’s branches when you [ask it about branches, versions, and merges](/guides/elevenagents-operate-architect-how-it-works#what-architect-can-see), so it can help you understand a proposal’s diff or summarize open reviews in a conversation. ## Next steps ::::card-grid :::card{title="Versioning" href="/guides/elevenagents-operate-versioning"} Branches, versions, and direct merging. ::: :::card{title="Architect" href="/guides/elevenagents-operate-architect"} The assistant built into ElevenAgents for iterating on an agent. ::: :::card{title="Triage" href="/guides/elevenagents-operate-triage"} Review conversation issues flagged for follow-up. ::: :::card{title="Experiments" href="/guides/elevenagents-operate-experiments"} Run A/B tests using branches and traffic deployment. ::: :::: ## Related pages - [Administration](./administration-index.md) - [API reference](./api-reference-index.md) - [Changelog](./changelog-index.md) - [ElevenAgents](./elevenagents-index.md) - [ElevenAPI](./elevenapi-index.md) - [ElevenCreative](./elevencreative-index.md) - [ElevenLabs Documentation Docs](../index.md) - [General Troubleshooting FAQ](./troubleshooting-index.md) - [General Website FAQ](./website-index.md) - [Help Center](./help-center-2-index.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.