---
title: GitHub Integration
description: How Claudear creates and manages pull requests
section: How It Works
order: 9
---

# GitHub Integration

Claudear automatically creates pull requests when Claude completes a task. This guide explains how PR creation works and how to customize it.

## How PRs Are Created

When Claude outputs `TASK_COMPLETE`:

1. **Push branch** to origin
2. **Create PR** via GitHub CLI
3. **Link to Linear** issue
4. **Update Linear** state to "In Review"

## PR Format

### Title

```
feat(ENG-123): Add user authentication
```

Format: `{type}({identifier}): {issue title}`

Types are inferred from the issue:
- `feat` - New features
- `fix` - Bug fixes
- `refactor` - Code refactoring
- `docs` - Documentation
- `test` - Test additions

### Body

```markdown
## Summary
Implements user authentication for the API.

## Linear Issue
Closes ENG-123

## Changes
- Added JWT token generation
- Created login/logout endpoints
- Added password hashing

---
Generated by Claudear
```

## GitHub CLI Authentication

Claudear uses `gh` for PR creation. Ensure it's authenticated:

```bash
gh auth status
```

If not authenticated:

```bash
gh auth login
```

Select:
- GitHub.com
- HTTPS
- Authenticate with browser

## Repository Setup

### Remote Configuration

Your repo needs an `origin` remote:

```bash
git remote -v
# origin  git@github.com:user/repo.git (fetch)
# origin  git@github.com:user/repo.git (push)
```

### Branch Protection

If your `main` branch has protection rules:

1. **Required reviews**: PRs will wait for review
2. **Required checks**: CI must pass
3. **No force push**: Already compatible

Claudear respects all branch protection rules.

## Customization

### Base Branch

By default, PRs target `main`. To change:

```bash
# In your repo's .claudear config (future feature)
base_branch: develop
```

### PR Template

Claudear uses a built-in template. Custom templates coming soon.

## Auto-Merge

When you move a Linear issue to "Done":

1. Claudear checks PR status
2. If all checks pass, merges via `gh pr merge`
3. Cleans up worktree and branch

### Merge Strategy

Default: Squash merge

```bash
gh pr merge --squash
```

This keeps your main branch history clean.

## Troubleshooting

### PR Creation Fails

**Check GitHub CLI:**
```bash
gh auth status
```

**Check remote access:**
```bash
git push origin HEAD --dry-run
```

**Check permissions:**
- You need write access to the repo
- GitHub CLI needs repo scope

### Wrong Base Branch

If PR targets wrong branch:

1. Close the PR
2. Update Claudear config
3. Retry the task

### CI Failures

If CI fails on the PR:

1. Review the failure
2. Add a comment on the Linear issue
3. Claude will see your feedback and fix
