> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Source control

Native GitHub integration for repository management and collaboration.

## Overview

Maestro provides first-class GitHub integration for:

* Creating repositories
* Cloning repositories and pull requests
* Creating and updating pull requests
* Managing branches and commits
* Collaborating with teams

**Access methods**:

* Natural language requests to Maestro
* Explicit commands (`/clone`, `/create`, `/pr`)
* Both trigger the same underlying workflows

**Authentication**: Link your GitHub account via top-right menu for private repository access.

## Create Repository

### Via Natural Language

```
"Create a new GitHub repository called my-awesome-project with MIT license and Python gitignore"
```

Maestro guides you through the configuration flow.

### Via Command

```
/create
```

Opens interactive repository creation flow.

### Configuration Options

**Required**:

* Repository name

**Optional**:

* Description
* Visibility (public or private, defaults to private)
* GitIgnore template (Python, Node, Go, etc.)
* License template (MIT, Apache-2.0, GPL, etc.)
* Organization (personal account or organization)
* Auto-clone (enabled by default)

### Auto-Clone Advantage

With auto-clone enabled (default):

1. Repository created on GitHub
2. Immediately cloned to your session
3. Ready to start working
4. Files synced to sandbox

**Seamless workflow**: Create → immediate development, no manual cloning.

### Smart Initial Content Handling

**If files exist in session** matching repository name:

```
You have files in: my-project/src/main.py, my-project/tests/...

Create repository "my-project" →
- Creates empty remote repository
- Pushes your existing session files as initial commit
- Respects .gitignore patterns
- Uses custom commit message if provided
- Single operation: create + push
```

**If no files exist**:

```
Create repository →
- Creates repository with selected templates
- Clones template files to session
- Standard template-based initialization
```

## Clone Repository

### Clone Your Repositories

**Via natural language**:

```
"Clone my backend-api repository, develop branch"
```

**Via command**:

```
/clone
```

When you run `/clone`, you'll be guided through selecting:

* **Privacy**: Private (from your authenticated account) or Public (any accessible repository)
* **Repository**: Choose from your account or enter a public URL
* **Branch/Commit**: Select from recent branches, enter a specific commit hash, or use the default branch

After cloning, files are immediately available to Maestro with all tools working, synced to the sandbox, and the clone record persists even after memory clearing.

### Clone Pull Requests

**Direct PR URL cloning**:

```
"Clone https://github.com/org/repo/pull/123"
```

Maestro automatically:

* Fetches PR metadata
* Determines source branch
* Handles forked PRs
* Clones appropriate branch
* Shows PR context (number, state, branch)

**Supported PR URL formats**:

```
github.com/owner/repo/pull/123
github.com/owner/repo/pull/123/files
github.com/owner/repo/pull/123/commits
github.com/owner/repo/pull/123/checks
```

**Use cases**:

* Review someone's PR
* Test PR changes
* Collaborate on feature branch
* Understand proposed changes

### Repository Size Limits

**Current limit**: 10 GB per repository (configurable)

**For larger repositories**:

* Clone specific subdirectories if possible
* Contact support for assistance with very large repositories
* Consider multi-session approach for modular development

### Clone Records

**Important behavior**:

```
Clone records persist even when you:
- Clear memories (/forget)
- Compact session (/compact)
- Hide files (/hidefiles)

Maestro never forgets which repository/branch you're working on.
```

Stored information:

* Repository URL
* Branch or commit
* Clone timestamp
* Whether cloned from PR

## Overwrite Clones: Pulling Remote Changes

### Purpose

Pull changes from remote repository into your session.

**When to use**:

* Teammate pushed commits
* Pull latest from main/develop
* Sync your PR branch with base
* Update dependencies or configuration

### How It Works

**Clone same repository again**:

```
Repository already cloned: backend-api (branch: feature-123)

Clone again from branch feature-123:
- Detects changed files
- Creates new iterations for changed files
- Adds any new files
- Preserves your iteration history
- Informs Maestro of changes
```

### Catchup Pattern

After overwrite clone, understand what changed:

**Example catchup workflow**:

```
I need to familiarize myself with recent changes to my PR.

Steps:
1. Clone my org/repo, branch main
2. Clone same repo again, branch my-feature-branch
3. Compute diffs between repositories
4. View the most important changed files
5. Give me comprehensive breakdown of what was accomplished

Focus on significant changes, not trivial updates.
```

**Maestro will**:

* Compare both clones
* Show diffs for all changed files
* Explain what changed and why
* Help you understand the current state

### Conflict Handling

**Current behavior**: Overwrites take remote changes as truth

**Important**: Push uncommitted session changes before overwrite cloning to avoid conflicts.

**Conflict resolution** (if needed):

```
After overwrite clone, local changes lost:

Maestro can recover by:
1. Viewing your previous iterations (still in history)
2. Reviewing remote changes
3. Intelligently merging lost work into new iterations

Request: "My changes from iteration 5 were lost. Restore that implementation while preserving the new remote changes."
```

## Pull Request Workflows

### Understanding Maestro's Workspace

**Critical concept**: Maestro's workspace is separate from git.

```
Work in session:
- Files exist in Maestro's internal storage
- Changes tracked via iterations
- Full history preserved
- Nothing pushed to git

Until you create/update PR:
- No branches created on remote
- No commits pushed
- Team doesn't see changes
```

**Implication**: Work as long as needed. Changes only go to GitHub when you explicitly create/update PR.

### Creating New PR

**Via natural language**:

```
"Create a pull request for my authentication changes. Title: Add JWT auth. Base branch: main."
```

**Via command**:

```
/pr
```

### PR Creation Flow

**Step 1: Branch Configuration**

* Review repository URL
* Set base branch (target)
* Set feature branch name
* Confirm or modify

**Step 2: Git Analysis**

* Determine if creating new branch or updating existing
* Identify changed files from base
* Compute statistics (lines added/removed)
* Handle three-way merge if updating existing

**Step 3: File Selection**

* Interactive UI shows all modified/new files
* Select which files to include in PR
* Can deselect files you don't want
* Shows cumulative vs incremental changes (for updates)

**Step 4: Final Confirmation**

* Provide/edit PR title and description
* Review file selection and statistics
* See complete diff of changes
* Confirm or cancel

**Step 5: Push and Create**

* Commits selected files
* Pushes to GitHub
* Opens pull request
* Adds you as reviewer (for OAuth limitation transparency)

### Updating Existing PR

**Full synchronization workflow**:

```
Update PR for feature-123:

Maestro will:
1. Show currently included files
2. Let you add/remove files
3. Compute diff against current PR state
4. Push updates to feature branch
5. PR automatically updates on GitHub
```

**Critical**: Updating is a **full sync**.

**Deselecting files** during update:

```
Previously included: auth.py, config.py, tests.py
You deselect: config.py

Result:
- config.py reverts to base branch state on remote
- Only auth.py and tests.py remain in PR
- Effectively removes config.py from PR
```

**Use case**: Splitting features across multiple PRs.

### PR Best Practices

**Before creating PR**:

```
1. Run full test suite
2. Verify all tests pass
3. Clean up WIP code and debug statements
4. Update documentation
5. Check code follows project conventions
6. Review all changes yourself

Then create PR.
```

**PR quality checklist**:

* Clear, descriptive title
* Comprehensive description explaining changes
* All tests passing
* No TODO comments unresolved
* Documentation updated
* Clean commit history

**Collaborative PRs**:

```
Working on same branch as teammate:
1. Overwrite clone to pull their changes
2. Review diffs to understand updates
3. Make your changes
4. Update PR to push your additions
```

## Branch Strategies

### Feature Branch per Session

**Recommended pattern**:

```
Session 1: Implement authentication
Branch: feature/auth-system
PR: Add JWT authentication

Session 2: Implement caching
Branch: feature/redis-cache
PR: Add Redis caching layer

Keeps PRs focused, reviewable, mergeable independently
```

### Multiple PRs from Single Session

**Possible but requires discipline**:

```
Session implements: auth + caching

PR 1: Select only auth files → Create PR on feature/auth
PR 2: Select only caching files → Create PR on feature/cache

Advantage: Single session, multiple deliverables
```

### Long-Running Feature Branches

**Pattern**:

```
Initial PR:
- Core implementation
- Basic tests
- Documentation

Update 1 (after feedback):
- Address review comments
- Add requested tests
- Improve error handling

Update 2 (after more feedback):
- Performance optimizations
- Edge case fixes
- Final polish

Each update uses /pr with same repository and branch
```

## Collaboration Workflows

### Reviewing Team Member's PR

```
"Clone https://github.com/org/repo/pull/456"

Maestro clones the PR branch, then:
"Review this PR for:
- Code quality issues
- Test coverage gaps
- Performance concerns
- Security vulnerabilities

Provide detailed feedback on each."
```

### Working on Forked Repositories

**Fork-based development**:

```
1. Fork repository on GitHub (manually or via Maestro)
2. Clone your fork to session
3. Implement changes
4. Create PR from your fork to upstream

PR tool handles:
- Pushing to your fork
- Creating PR to upstream repository
- Managing cross-repository workflow
```

### Team Coordination Patterns

**Sequential collaboration**:

```
Developer A:
- Creates feature branch
- Implements partial feature
- Creates PR (draft)

Developer B (in new session):
- Clones PR from A
- Continues implementation
- Updates same PR
- Marks as ready for review
```

**Parallel collaboration**:

```
Team works on main develop branch:
- Each developer uses separate feature branches
- Create focused PRs for specific parts
- PRs reviewed and merged independently
- Periodic overwrite clones to stay synced
```

## Advanced Workflows

### Multi-Repository Projects

**Working across repositories**:

```
Clone frontend repository
Clone backend repository
Clone shared library

Implement feature touching all three:
- Make changes in each repository
- Create separate PRs for each
- Link PRs in descriptions
- Coordinate reviews
```

### Release Preparation

```
Preparing v2.0 release:

Clone from main branch:
"Review all changes since v1.5 tag"

Maestro:
- Identifies changed files
- Creates comprehensive changelog
- Documents breaking changes
- Validates backward compatibility

Update documentation:
- API changes
- Migration guides
- Release notes

Create PR with all release docs
```

### Hotfix Workflow

```
Critical bug in production:

1. Clone from production branch
2. Reproduce issue in sandbox
3. Implement minimal fix
4. Validate fix doesn't break anything
5. Create PR directly to production branch
6. Minimal, surgical change for fast review
```

## Troubleshooting

### Clone Failed

**Error**: Repository too large

**Solution**: Current limit is 10 GB. For larger repos, consider:

* Cloning specific subdirectories
* Multi-session approach
* Contact support for special cases

**Error**: Authentication failed

**Solution**: Ensure GitHub account linked in top-right menu.

**Error**: Branch not found

**Solution**: Verify branch name spelling. Try default branch.

### PR Creation Failed

**Error**: No changes detected

**Cause**: Files not modified or not selected

**Solution**: Make changes, ensure Apply Changes ran, select files in PR flow.

**Error**: Branch already exists

**Cause**: Feature branch name conflicts with existing branch

**Solution**: Choose different branch name or update existing PR.

### PR Update Not Showing Changes

**Check**:

1. Did you apply changes before creating PR?
2. Were files actually modified?
3. Did you select the changed files in PR flow?

**Verify**:

```
Use Compute Diffs to see what changed
Ensure Apply Changes ran successfully
Check file selection in PR creation UI
```

## Best Practices

### Repository Organization

**Session file structure mirrors git**:

```
/repo-name/
    src/
    tests/
    docs/
    ...

Matches: github.com/org/repo-name
Makes PR creation seamless
```

### Commit Messages

**Let Maestro generate**:

* Based on actual changes
* Follows conventional commit format
* Descriptive and accurate

**Or provide custom**:

```
When creating PR, specify commit message:
"feat: implement JWT authentication with refresh tokens"
```

### PR Descriptions

**Effective PR descriptions include**:

* What changed and why
* Testing approach
* Performance impact
* Breaking changes (if any)
* Dependencies or prerequisites
* Screenshots for UI changes

**Template**:

```markdown theme={null}
## Changes
[What was implemented]

## Testing
[How it was validated]

## Performance
[Benchmark results if relevant]

## Breaking Changes
[None or list them]

## Notes
[Additional context]
```

### Incremental PRs

**Small, focused PRs** are easier to review:

```
Instead of giant PR:
- authentication
- caching
- monitoring
- logging

Create sequential PRs:
1. PR #1: Add authentication (merged)
2. PR #2: Add caching (builds on #1, merged)
3. PR #3: Add monitoring (builds on #2, merged)
4. PR #4: Add logging (builds on #3)
```

## Integration with CI/CD

### Pre-PR Validation

Ensure CI will pass:

```
Before creating PR:
1. Run full test suite locally (in sandbox)
2. Run linters and formatters
3. Check code coverage
4. Run any CI scripts locally
5. Verify build succeeds

Only create PR after local validation passes.
```

### GitHub Actions Integration

**Validate CI config before pushing**:

```
"Review our GitHub Actions workflow and ensure the new authentication module will be tested correctly in CI"

Maestro:
- Examines .github/workflows/*.yml
- Identifies if new tests will run
- Suggests workflow updates if needed
- Validates before PR creation
```

## Advanced Patterns

### Stacked PRs

**Building features incrementally**:

```
Base: main

PR #1: feature/core → main
  (Core infrastructure)

PR #2: feature/api → feature/core
  (API layer, depends on core)

PR #3: feature/ui → feature/api
  (UI, depends on API)

Each PR reviewable independently
Merge order: #1, then #2, then #3
```

### Cross-Repository Features

**Feature spans multiple repos**:

```
Repository A (backend):
- API changes
- Create PR in repo A

Repository B (frontend):
- UI changes consuming new API
- Create PR in repo B

Link PRs in descriptions
Coordinate reviews and merges
```

### Emergency Patches

**Critical production fix**:

```
1. Clone from production branch
2. Implement minimal fix
3. Test thoroughly in sandbox
4. Create PR with "hotfix/" prefix
5. Request immediate review
6. Small, focused change for fast approval
```

## Repository Management

### Multiple Clones in Single Session

**Use cases**:

```
Clone same repo, different branches for comparison:
- Clone org/repo branch main → See production state
- Clone org/repo branch develop → See upcoming changes

Compare implementations:
- Clone org/repo-python branch main
- Clone org/repo-node branch main
- Analyze approach differences
```

### Repository Metadata

**Maestro tracks**:

* All cloned repositories
* Branch or commit for each
* Clone timestamps
* Whether from PR URL

**Access**:

```
"Show me all cloned repositories"
"Which branch of the backend am I on?"
"When did I last pull from main?"
```

This information persists across memory operations.

## GitHub API Integration

### Reading Repository Data

Maestro can query GitHub for:

* Issues and pull requests
* Workflow runs and status
* Repository metadata
* Branch information

**Example**:

```
"Show me all open issues labeled 'bug' in the backend repo"

Maestro uses GitHub API to fetch and display issues.
```

### Commenting on PRs

```
"Add a review comment to PR #123 suggesting optimization in the auth logic"

Maestro:
- Views PR
- Adds inline or general comments
- Can suggest code changes
- Participates in PR discussion
```

## Limitations and Considerations

### Authentication Required

**For private repositories**:

* Must link GitHub account
* OAuth authentication
* Permissions respected (can only access what you can access)

**For public repositories**:

* No authentication needed
* Clone any public repo

### Current Limitations

* **No automated conflict resolution**\*\* Manual guidance needed\
  **Repository size cap**: 10 GB configurable limit
* **No git rebase/squash**\*\* Linear history for now
* **No submodule support yet**\*\* Planned enhancement

### Workarounds

**Conflicts**:

* Maestro can guide resolution by viewing both versions
* Manually merge via intelligent editing
* Use iteration history to track changes

**Large repositories**:

* Clone subsets
* Contact support for special cases

## Best Practices Summary

### Repository Operations

* **Clone early**: Get code context before implementation
* **Update regularly**: Overwrite clone to stay current
* **Track branches**: Know which branch you're on
* **Document clones**: Maestro tracks, but you should understand

### Pull Request Creation

* **Test first**: All tests must pass before PR
* **Clean up**: Remove WIP code, debug statements
* **Document changes**: Clear descriptions
* **Review yourself**: Check diffs before submitting
* **Small PRs**: Easier to review and merge

### Collaboration

* **Communicate intent**: PR descriptions explain why
* **Link related work**: Reference issues, other PRs
* **Respond to feedback**: Update PRs based on reviews
* **Keep synced**: Regular overwrite clones on active branches

## Next Steps

With source control mastery:

* **[Session Strategies](getting-started/session-strategies)**: Patterns for different project types
* **[Advanced Features](getting-started/advanced-features)**: Power user capabilities
* **[Integrations & Credentials](getting-started/integrations-secrets)**: External service integration
* **[Troubleshooting](../reference/troubleshooting)**: Common issues and solutions