GitHub Integration

Pilot monitors GitHub issues and automatically implements tasks.

Setup

1. Create a Personal Access Token

1. Go to GitHub Settings → Developer Settings → Personal Access Tokens
2. Create a token with these scopes:
   • repo (full access)
   • workflow (if using GitHub Actions)

2. Configure Pilot

# ~/.pilot/config.yaml
github:
  token: ${GITHUB_TOKEN}
  poll_interval: 30s
  labels:
    - pilot

3. Start Pilot

pilot start --github

Creating Tasks

Label any issue with pilot to queue it for execution:

gh issue create \
  --title "Add user authentication" \
  --label pilot \
  --body "Implement JWT-based authentication with refresh tokens"

Issue Format

For best results, structure issues like this:

## Description
[What needs to be done]
 
## Requirements
- [ ] Requirement 1
- [ ] Requirement 2
 
## Context
[Any relevant context or links]
 
## Acceptance Criteria
- [ ] Tests pass
- [ ] Documentation updated

Pull Request Flow

When Pilot completes a task:

1. Creates a new branch: pilot/GH-{issue-number}
2. Commits changes with conventional commit messages
3. Creates a PR linked to the issue
4. Adds a summary comment on the issue

Labels

Webhooks (Advanced)

For real-time processing, configure a webhook:

pilot webhook setup --github

This eliminates polling delay for instant task pickup.

Projects V2 Board Sync

Pilot can automatically update your GitHub Projects V2 board as tasks progress. Issues move through configurable columns: In Progress → Review → Done (or Failed).

adapters:
  github:
    project_board:
      enabled: true
      project_number: 5
      statuses:
        in_progress: "In Progress"
        review: "In Review"
        done: "Done"
        failed: "Blocked"

Full board sync documentation →

Rate Limiting & Reliability

Pilot is designed to run 24/7 without hitting GitHub API rate limits or database issues.

Rate Limit Handling

The scheduler automatically tracks GitHub API quota via response headers:

• On 429 (rate limited): Automatic retry with RetryBuffer (5-minute safety margin before reset)
• Exponential backoff: Transient failures trigger progressive delays (added in v0.34.0)
• Check interval: 1-minute default polling cycle

Reducing API Usage

Use webhooks instead of polling — Zero API quota consumed for issue detection:

pilot start --github --tunnel

Increase poll interval — If webhooks aren’t an option:

# ~/.pilot/config.yaml
orchestrator:
  execution:
    poll_interval: 60s  # Default is 30s

Stale label cleanup — Configurable threshold reduces label API calls:

orchestrator:
  stale_cleanup:
    threshold: 2h  # How long before in-progress labels are cleaned

SQLite Reliability (v1.5.2+)

Pilot uses SQLite for local state and history. The following reliability measures ensure stable 24/7 operation:

These settings are automatic — no configuration needed.