Pull Requests

Pull requests (PRs) let you propose changes, get reviews, and merge code into protected branches.

Creating a Pull Request

Create a Branch

git checkout -b feature/new-feature

Make Changes and Push

git add .
git commit -m "Add new feature"
git push -u origin feature/new-feature

Open Pull Request

Go to the repository in the dashboard and click New Pull Request, or use the API:

curl -X POST "https://statly.live/api/v1/code/repos/org/repo/pulls" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add new feature",
    "body": "This PR adds...",
    "sourceBranch": "feature/new-feature",
    "targetBranch": "main"
  }'

PR States

State	Description
`draft`	Work in progress, not ready for review
`open`	Ready for review
`merged`	Successfully merged
`closed`	Closed without merging

Diff Viewer

The diff viewer supports:

Side-by-side and unified views
Syntax highlighting in diffs
Expand context to see more lines
File tree navigation for multi-file changes
Image diffs for visual changes
Word-level diffs for prose changes

Code Review

Requesting Reviews

Reviewers are automatically assigned based on:

CODEOWNERS file rules
Manual assignment in the PR

Review States

State	Description
`pending`	Review not yet submitted
`approved`	Reviewer approves changes
`changes_requested`	Reviewer requests changes
`commented`	Reviewer left comments only

Inline Comments

Click any line in the diff to add a comment:

### Suggestion
Consider using `const` instead of `let` here since the value doesn't change.
 
```suggestion
const value = calculateValue();


### Suggested Changes

Use the `suggestion` code block to propose specific changes:

````markdown
```suggestion
const newCode = "fixed version";


The author can apply suggestions with one click.

## CODEOWNERS

Create a `CODEOWNERS` file to automatically assign reviewers:

```text
# CODEOWNERS file

# Default owners for everything
* @team-lead

# Frontend code
/src/components/** @frontend-team
*.tsx @frontend-team
*.css @frontend-team

# Backend code
/src/api/** @backend-team
*.go @backend-team

# DevOps
/infra/** @devops-team
Dockerfile @devops-team
```

## Merge Strategies

### Merge Commit

Creates a merge commit preserving full history:

```
*   Merge pull request #123
|\
| * Feature commit 3
| * Feature commit 2
| * Feature commit 1
|/
* Previous main commit
```

### Squash and Merge

Combines all commits into a single commit:

```
* Add new feature (#123)
* Previous main commit
```

### Rebase and Merge

Replays commits on top of target branch:

```
* Feature commit 3
* Feature commit 2
* Feature commit 1
* Previous main commit
```

## Merge Checks

PRs must pass these checks before merging (if configured):

| Check | Description |
|-------|-------------|
| **Required approvals** | Minimum number of approving reviews |
| **No changes requested** | No outstanding change requests |
| **CI passing** | All CI checks must pass |
| **No conflicts** | Branch must be mergeable |
| **Signed commits** | All commits must be GPG signed |
| **Linear history** | No merge commits in the PR |

<Callout type="info">
  See [Branch Protection](/code/branch-protection) to configure these requirements.
</Callout>

## Auto-Merge

When auto-merge is enabled, PRs merge automatically when all checks pass:

1. Enable auto-merge on the PR
2. Select merge strategy
3. PR merges when:
   - All required approvals obtained
   - CI checks pass
   - AI review approves (if configured)
   - No conflicts

## Stale PRs

PRs are automatically managed:

| Days Open | Action |
|-----------|--------|
| 30 days | Warning label added |
| 90 days | Auto-closed (configurable) |

## Linking Issues

Reference issues in PR descriptions to link them:

```markdown
Fixes #123
Closes #456
Resolves #789
```

When the PR merges, linked issues are automatically closed.

## API Reference

### List Pull Requests

```bash
GET /api/v1/code/repos/{org}/{repo}/pulls?state=open

# Response
{
  "pullRequests": [
    {
      "id": "pr_xxx",
      "number": 42,
      "title": "Add new feature",
      "state": "open",
      "sourceBranch": "feature/new-feature",
      "targetBranch": "main",
      "author": { "name": "John", "email": "[email protected]" },
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}
```

### Get Pull Request

```bash
GET /api/v1/code/repos/{org}/{repo}/pulls/{number}
```

### Create Pull Request

```bash
POST /api/v1/code/repos/{org}/{repo}/pulls
Content-Type: application/json

{
  "title": "Add new feature",
  "body": "Description...",
  "sourceBranch": "feature/new-feature",
  "targetBranch": "main",
  "isDraft": false
}
```

### Merge Pull Request

```bash
POST /api/v1/code/repos/{org}/{repo}/pulls/{number}/merge
Content-Type: application/json

{
  "strategy": "squash",
  "commitMessage": "Custom merge message",
  "deleteBranch": true
}
```

### Add Review

```bash
POST /api/v1/code/repos/{org}/{repo}/pulls/{number}/reviews
Content-Type: application/json

{
  "state": "approved",
  "body": "LGTM!"
}
```

### Add Comment

```bash
POST /api/v1/code/repos/{org}/{repo}/pulls/{number}/comments
Content-Type: application/json

{
  "body": "Comment text",
  "path": "src/index.ts",
  "line": 42
}
```

Repositories CI/CD