GitHub Source

Fetch specifications from GitHub Issues to turn them into built projects.

Authentication

GitHub source works in two modes:

1. GitHub CLI (Recommended)

If you have GitHub CLI installed and authenticated:

gh auth login

No additional configuration needed.

2. Personal Access Token

ralph-starter config set github.token ghp_xxxxxxxxxxxx

Create a token at GitHub Settings > Developer settings > Personal access tokens.

Required scopes:

• repo (for private repositories)
• public_repo (for public repositories only)

Usage

# Fetch all open issues from a repo
ralph-starter run --from github --project owner/repo

# Filter by label
ralph-starter run --from github --project owner/repo --label "ready-to-build"

# Filter by status
ralph-starter run --from github --project owner/repo --status open

# Limit results
ralph-starter run --from github --project owner/repo --limit 5

# Combine filters
ralph-starter run --from github --project owner/repo --label "sprint-1" --status open --limit 10

Fetching a Single Issue

Fetch a specific issue by number:

# By issue number
ralph-starter run --from github --project owner/repo --issue 123

# By full URL
ralph-starter run --from github --project https://github.com/owner/repo/issues/123

This fetches:

• Issue title and body
• Labels and state
• All comments

Perfect for building features from well-specified issues.

Options

Option	Description	Default
--project	Repository in owner/repo format	Required
--label	Filter by label name	None
--status	Filter by status (open, closed, all)	open
--limit	Maximum issues to fetch	20
--issue	Specific issue number to fetch	None

Issue Format

GitHub issues are converted to specs with:

• Title → Spec title
• Body → Spec description
• Labels → Tags
• Comments → Additional context

Example Issue

# Add user authentication

## Description
Add email/password authentication to the app.

## Requirements
- Login form
- Registration form
- Password reset flow
- Session management

## Acceptance Criteria
- [ ] Users can register with email
- [ ] Users can log in
- [ ] Users can reset password

Generated Spec

# Add user authentication

Source: GitHub Issue #42 (owner/repo)
Labels: feature, authentication

## Description
Add email/password authentication to the app.

## Requirements
- Login form
- Registration form
- Password reset flow
- Session management

## Acceptance Criteria
- [ ] Users can register with email
- [ ] Users can log in
- [ ] Users can reset password

Preview Issues

Before running, you can preview what will be fetched:

ralph-starter source preview github --project owner/repo --label "ready"

Test Connection

Verify your authentication:

ralph-starter source test github

Tips

1. Use labels effectively - Create a "ready-to-build" or "ralph" label for issues that are well-specified
2. Write detailed issues - Include requirements, acceptance criteria, and context
3. One issue = one feature - Keep issues focused for better results