Branch Workflow

Overview

When RepoBird executes a run, it follows a specific Git workflow to ensure clean, isolated changes that integrate smoothly with your existing development process. This guide explains how RepoBird manages branches and creates pull requests.

The RepoBird Branch Workflow

Step-by-Step Process

1. Starting Point: Source Branch

   • RepoBird begins from the source branch you specify
   • This is typically your default branch (e.g., main or master)
   • The source branch must exist in your repository

2. Automatic Work Branch Creation

   • RepoBird creates a unique, auto-generated branch name
   • Format: repobird/agent-[unique-id] (e.g., repobird/agent-bd0c22e0)
   • This branch is created from your source branch
   • Each run gets its own isolated branch

3. Code Generation and Changes

   • All code modifications happen in the auto-generated work branch
   • Changes are isolated from your main development branches
   • Multiple agents can work simultaneously without conflicts

4. Commits and Push

   • RepoBird commits changes with descriptive commit messages
   • All commits are atomic and follow best practices
   • The work branch is pushed to your GitHub repository

5. Pull Request Creation

   • A pull request is opened from the work branch to your target branch
   • The target branch is typically the same as your source branch (e.g., main)
   • The PR includes comprehensive descriptions and change summaries

Branch Configuration Options

UI Dashboard

When using the RepoBird dashboard to trigger runs:

• Source Branch: Select an existing branch to start from (defaults to repository's default branch)
  • Must be an existing branch in your repository
  • Custom branch names are not allowed - select from available branches
• Target Branch: Choose where the PR should merge to (defaults to the source branch)
  • Must be an existing branch in your repository
  • If not specified, PR will merge back to the source branch
  • Custom branch names are not allowed - select from available branches

GitHub Comments

When triggering via GitHub comments, you can specify branches:

@RepobirdBot run source:develop target:main Implement the feature

• source:branch-name - Branch to create the work branch from (must exist)
• target:branch-name - Branch the PR will merge into (must exist)

If not specified:

• Source defaults to your repository's default branch
• Target defaults to the source branch (PR merges back to where it started)

Why This Workflow?

Clean Isolation

Each run operates in its own branch, preventing conflicts between multiple concurrent runs or manual development work.

Predictable Naming

The repobird/agent-* pattern makes it easy to identify RepoBird-generated branches in your repository.

Safe Integration

By creating PRs instead of directly pushing to main branches, you maintain full control over what gets merged.

Parallel Execution

Multiple agents can work on different issues simultaneously, each in their own isolated branch.

Common Scenarios

Single Branch Development

If you work primarily on main:

• Source: main
• Target: main
• Result: PR from repobird/agent-xyz → main

Feature Branch Workflow

For feature branch development:

• Source: develop
• Target: develop
• Result: PR from repobird/agent-xyz → develop

Hotfix Scenario

For urgent fixes:

• Source: production
• Target: production
• Result: PR from repobird/agent-xyz → production

Best Practices

1. Always Review PRs: Even though RepoBird generates high-quality code, always review before merging
2. Use Descriptive Instructions: Clear instructions lead to better branch names in commit messages
3. Leverage Branch Protection: Use GitHub's branch protection rules on your target branches
4. Clean Up Old Branches: Delete merged RepoBird branches to keep your repository tidy

Important Changes (January 2025)

Target Branch Behavior

RepoBird now defaults the target branch to the source branch when not specified. This means:

• If you only specify a source branch, the PR will merge back to that same branch
• This is the standard workflow for feature development
• You can still specify a different target branch if needed

Branch Validation

All branches must exist before starting a run:

• Source branch: Must exist (validated before run starts)
• Target branch: Must exist if specified (validated before run starts)
• Custom branch names are no longer allowed - you must select from existing branches
• This prevents errors and ensures smooth PR creation

FAQ

Q: Can I specify a custom work branch name? A: No, RepoBird automatically generates unique branch names to ensure no conflicts.

Q: What happens if the source or target branch doesn't exist? A: RepoBird validates that both branches exist before starting the run. If either branch doesn't exist, you'll receive an error message immediately asking you to create the branch first or select a different one.

Q: Can I create a PR to a branch that doesn't exist yet? A: No, the target branch must exist. Create the branch first in GitHub, then run RepoBird. Alternatively, leave the target empty to merge back to the source branch.

Q: Can RepoBird work on existing branches? A: When commenting on an existing PR, RepoBird can push additional commits to that PR's branch.

Q: How do I handle merge conflicts? A: Review and resolve conflicts in the GitHub PR interface, just like any other pull request.