GitHub Integration

How Clotion creates and manages pull requests

GitHub Integration

Clotion 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 Notion card (via PR URL property)
4. Update Notion status to "In Review"

PR Format

Title

feat(CLO-123): Add user authentication

Format: {type}({clotion-id}): {card title}

Types are inferred from the task:

• feat - New features
• fix - Bug fixes
• refactor - Code refactoring
• docs - Documentation
• test - Test additions

Body

## Summary
Implements user authentication for the API.

## Notion Card
CLO-123

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

---
Generated by Clotion

GitHub CLI Authentication

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

gh auth status

If not authenticated:

gh auth login

Select:

• GitHub.com
• HTTPS
• Authenticate with browser

Repository Setup

Remote Configuration

Your repo needs an origin remote:

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

Clotion respects all branch protection rules.

Customization

Base Branch

By default, PRs target main. To change:

# In .env
BASE_BRANCH=develop

PR Template

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

Auto-Merge

When you move a Notion card to "Done":

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

Merge Strategy

Default: Squash merge

gh pr merge --squash

This keeps your main branch history clean.

Notion Updates

When a PR is created, these Notion properties update:

This lets you:

• Click directly to the PR from Notion
• See PR status at a glance
• Track which branch corresponds to which task

Troubleshooting

PR Creation Fails

Check GitHub CLI:

gh auth status

Check remote access:

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 BASE_BRANCH in .env
3. Retry the task

CI Failures

If CI fails on the PR:

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

PR URL Not Updating in Notion

If the PR is created but Notion doesn't update:

1. Check Clotion logs for errors
2. Verify Notion integration has write access
3. The property might need to be created first (restart Clotion)