GitHub

GitHub

Roll agents are designed to work seamlessly with your GitHub workflow. This guide covers best practices for branch management, pull requests, and CI/CD integration.

Branch Management

Automatic Branch Creation

When an agent is launched on a Linear issue, it automatically creates a dedicated branch following this naming convention:

[workspace-branch-prefix]/[issue-number]-[issue-title]

For example, if your workspace prefix is roll and the issue is ENG-123: Fix login bug, the branch would be:

roll/ENG-123-fix-login-bug

Branch Reuse

All subsequent agents working on the same issue will:

  • Automatically detect and use the existing branch
  • Continue work from where the previous agent left off
  • Maintain a single branch per issue for clean history

Pull Request Workflow

Creating PRs

When an issue is complete, the agent will:

  1. Push all commits to the feature branch
  2. Create a pull request back to your default branch
  3. Include issue context and implementation details in the PR description
  4. Link the PR to the Linear issue for traceability

Staging Branch Strategy

We strongly recommend using a staging branch as an intermediate step:

feature-branch → staging → main

Benefits:

  • Manual review and testing before production
  • Prevents unexpected changes to main branch
  • Allows batching multiple features for coordinated releases
  • Provides a safety net for agent-generated code

Setup:

  1. Create a staging branch from main
  2. Set staging as the default target for agent PRs
  3. Manually review and merge staging → main when ready

CI/CD Integration

Enabling Build and Test Actions

Roll agents run in lightweight containers with limited resources. To enable comprehensive building and testing, integrate with your CI/CD pipeline through Linear actions.

Setting Up Actions

  1. Navigate to Team Settings in Linear

  2. Add Custom Actions for common tasks:

    • Build: Triggers your CI build pipeline
    • Test: Runs your test suite
    • Deploy: Initiates deployment workflows

  3. Grant Agent Access in the Roll team editor:

    allowedActions:
  - build
  - test
  - deploy-staging

Team Prompt Configuration

Include action usage in your team prompt:

When completing implementation tasks:
1. Run the 'build' action to verify compilation
2. Run the 'test' action to ensure all tests pass
3. Only create a PR after successful build and test
 
Available actions:
- build: Compiles the project and reports errors
- test: Runs the full test suite
- deploy-staging: Deploys to staging environment

Benefits of Action Integration

  • Clear Audit Trail: Every build/test run is logged in Linear
  • Resource Efficiency: Offloads heavy operations to your CI infrastructure
  • Consistency: Agents use the same build/test pipeline as developers
  • Visibility: Team can monitor agent progress through CI status

Best Practices

1. Branch Protection Rules

Configure GitHub branch protection for main and staging:

  • Require pull request reviews
  • Require status checks to pass
  • Dismiss stale reviews on new commits
  • Include administrators in restrictions

2. PR Review Process

Establish clear review criteria for agent-generated PRs:

  • Code quality and style consistency
  • Test coverage for new features
  • Performance implications
  • Security considerations

3. Commit Messages

Agents generate descriptive commit messages, but you can guide their format through team prompts:

Use conventional commit format:
- feat: New features
- fix: Bug fixes
- refactor: Code improvements
- test: Test additions/changes
- docs: Documentation updates

4. Issue Completion Criteria

Define clear completion criteria in your Linear issues:

  • All tests passing
  • Documentation updated
  • PR created and linked
  • Review requested from appropriate team members

Example Workflow

Here’s a complete workflow from issue to deployment:

  1. Issue Created in Linear: ENG-456: Add user notifications
  2. Agent Launched via mention or assignment
  3. Branch Created: roll/ENG-456-add-user-notifications
  4. Implementation completed by agent
  5. Build Action triggered to verify compilation
  6. PR Created to staging branch
  7. Code Review by team members
  8. Merge to Staging after approval
  9. Testing in Staging environment
  10. Merge to Main when verified
  11. Issue Closed automatically via PR integration

This workflow ensures quality control while maintaining efficiency.

Prompting