# Pull requests

> Sypnia Cloud only: how Sypnia opens a pull request with the fix, what it contains, what the GitHub App is allowed to do, what it never does, and the limits per plan.

Applies to: Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/agent/pull-requests/

For agents: Sypnia Cloud pull requests: when one can be opened (confidence high or medium, repository connected), branch sypnia/<problem slug>, contents of the PR (change, test, description), GitHub App permissions (Contents RW, Pull requests RW, Metadata R), what it never does (no merge, no push to default branch), failure modes, and fixes per month by plan.

**\[Cloud]** On Sypnia Cloud, a problem can arrive with its fix as a pull request. Sypnia writes the change and a test on a branch of your repository and opens the pull request. A person reads it and merges it. **Sypnia never merges.**

The open-source engine does not open pull requests. There, hand the fix to your own coding agent with [the prompt](https://docs.sypnia.com/agent/the-prompt) or the [MCP server](https://docs.sypnia.com/mcp/connect). It is the same information.

## Before you start

- The project is connected to a repository through the Sypnia GitHub App. See [The GitHub App](https://docs.sypnia.com/cloud/github-app) for how to install it and choose repositories.
- Your app sends its `release` as the git commit, so Sypnia knows which code was running. See [Releases and source maps](https://docs.sypnia.com/concepts/releases-and-source-maps).

## When a pull request can be opened

| Condition                                                  | Why                                                                                                                 |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| The analysis is `ready` with confidence `high` or `medium` | Sypnia does not write a fix it cannot justify. With `low`, or `not_enough_evidence`, the button is off and says why |
| The problem is open                                        | A resolved or ignored problem needs no fix                                                                          |
| The problem has no open pull request from Sypnia           | One at a time per problem                                                                                           |
| The organization has fixes left this month                 | See the limits below                                                                                                |

Then it opens in one of two ways:

- **You ask.** The button «Open pull request» on the problem, or [`POST /v1/problems/{problem}/pull-request`](https://docs.sypnia.com/api/problems).
- **By itself**, if you turn it on: the project setting `agent.auto_pull_requests` set to `high_confidence` opens one for every analysis with confidence `high`. It is off by default.

## What happens

### 1. Sypnia reads the repository

Through the GitHub App, at the commit of the release where the problem happens. It reads the files the analysis names and the ones around them. Your code is used for this pull request and is not kept afterwards.

### 2. It writes the change and a test

The smallest change that removes the cause, and a test that fails without it, in your project's own test framework. If the project has no tests, the pull request has the change only and says so.

### 3. It opens the pull request

On a new branch named `sypnia/<problem slug>`, for example `sypnia/pay-button-does-nothing`, against your default branch.

**You should see:**Within a few minutes the problem shows the pull request, and the `problem.pull_request_opened` webhook is sent.

### 4. Your checks run, a person reviews

Sypnia does not run your code. Your own CI runs on the pull request, as for any other. You read it, ask for changes or change it yourself, and merge.

### 5. After the merge

When the fix is deployed, mark the problem resolved, or let your coding agent do it. If the failure comes back, the problem reopens by itself.

## What the pull request contains

| Part        | Content                                                                                                                                                                                               |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Title       | What the change does, in the imperative: «Read the cart total from its new field»                                                                                                                     |
| Description | The problem's sentence, who it hit and since when; the cause with its evidence; what was changed and why; how the test covers it; links to the problem and to a session with a replay; the confidence |
| Commits     | One for the change, one for the test, authored by `sypnia[bot]`                                                                                                                                       |
| Files       | Only the files the fix needs. Never workflow files, lock files, or configuration of your CI                                                                                                           |

The description never contains names, e-mails or ids of the people affected.

## What the GitHub App may do

The app asks for three permissions, on the repositories you choose and no others.

| Permission    | Access         | What it is for                                                           |
| ------------- | -------------- | ------------------------------------------------------------------------ |
| Contents      | Read and write | Read the code; push the branch `sypnia/<problem slug>`                   |
| Pull requests | Read and write | Open the pull request and update its description                         |
| Metadata      | Read           | Required by GitHub for any app: the repository's name and default branch |

## What it never does

- It never merges a pull request, and never approves one.
- It never pushes to your default branch or to any branch it did not create. It never force-pushes over someone else's commits.
- It never changes workflows, secrets, settings, collaborators or branch protection. It has no permission to.
- It never opens more than one pull request for a problem at a time, and never reopens one you closed.
- It never runs your code or your tests.

Protect your default branch on GitHub so that every pull request needs a review. Sypnia's pull requests then follow the same rule as anyone's.

## When it cannot

| What you see                                            | Why                                                                                                                                                                                                                      |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The button is off: «Not enough evidence to write a fix» | The analysis has no cause, or its confidence is `low`                                                                                                                                                                    |
| The button is off: «Connect a repository»               | The project has no repository through the GitHub App                                                                                                                                                                     |
| `failed`, with a reason, on the problem                 | Sypnia read the code and could not write a change it trusts: the code at that commit does not match the analysis, or the fix would touch more than it should. Nothing was opened and it did not count against your limit |
| The pull request is open and your checks fail           | Sypnia does not retry by itself. Fix it on the branch, or close it and ask again                                                                                                                                         |

## Limits per plan

A pull request counts when it is opened. Asking again for the same problem counts again. The count is per organization, per calendar month in UTC.

| Plan    | Pull requests Sypnia opens a month |
| ------- | ---------------------------------- |
| Free    | 5                                  |
| Builder | 50                                 |
| Team    | 300                                |

These numbers come from the [plans](https://docs.sypnia.com/cloud/plans-and-limits) and are shown, with what you have used, by [`GET /v1/usage`](https://docs.sypnia.com/api/projects-keys-and-tokens). At the limit the button says when the count resets; the analysis and the prompt keep working.
