/github-sync

description: "[DEPRECATED] Use sw-github:sync-spec instead. Legacy increment-based GitHub sync."

DEPRECATED: Use `sw-github:sync-spec` Instead

> **This command is deprecated as of v1.0.235.** The increment-based sync has been replaced by spec-based sync. > > **Migration:** > - For spec-to-GitHub Issue sync: `sw-github:sync-spec <spec-id>` > - For batch sync: `sw-github:sync-spec --all` > - For pull direction: `sw-github:sync-spec <spec-id> --direction from-github` > > The old increment-based sync created issues per-task. The new spec-based sync creates issues per-User-Story, > which is the correct granularity for GitHub project management.

---

Legacy: Sync Increment with GitHub Issue (Multi-Project)

Pre-Sync Requirements (Read First!)

⛔ MANDATORY: Sync Living Docs BEFORE GitHub Sync

**GitHub sync reads FROM living docs.** If living docs are stale, GitHub issues will have outdated content.

**You MUST run `sw:sync-specs` (or ensure it ran) BEFORE this command:**

# STEP 1: Ensure living docs are current (MANDATORY)
sw:sync-specs <increment-id>

# STEP 2: Then sync to GitHub
sw-github:sync <increment-id>

**Why?**

• GitHub issues are generated FROM `.specweave/docs/internal/specs/FS-XXX/`
• If you skip sync-specs, GitHub will show stale user stories/ACs
• `sw:sync-progress` calls sync-specs automatically, but `sw-github:sync` does NOT

**If you're calling this directly (not via sw:sync-progress), run sync-specs first!**

---

Step 0: Detect Project Structure

# Check for living docs structure
if [ -d ".specweave/docs/internal/specs" ] && [ -n "$(ls -A .specweave/docs/internal/specs/*/FEATURE.md 2>/dev/null)" ]; then
    echo "✅ Living docs found → Use Feature Sync"
else
    echo "⚠️ No living docs → Use Increment Sync (brownfield)"
fi

Sync Path Decision:

| Structure | Command | Issue Format | |-----------|---------|--------------| | **Living docs exist** (`.specweave/docs/internal/specs/FS-XXX/`) | Use `github-feature-sync-cli.ts` | `[FS-XXX][US-YYY] Title` | | **Increment only** (brownfield, no living docs) | Use `github-feature-sync-cli.ts` | `[FS-XXX] Title` with ACs |

For Projects with Living Docs:

Use the Feature Sync CLI:

# Run feature sync via CLI
specweave sync-progress <increment-id>

# Example
specweave sync-progress 0062

---

Synchronize the current state of a SpecWeave increment with its GitHub issue across multiple repositories. Supports multi-profile management, time range filtering, and rate limit protection.

Usage

sw-github:sync <increment-id> [options]

Arguments

• `increment-id`: Increment ID (e.g., `0004` or `0004-plugin-architecture`)

Options

Sync Options

• `--profile <id>`: Use specific sync profile (skip selection prompt)
• `--time-range <preset>`: Time range for sync (`1W`, `2W`, `1M`, `3M`, `6M`, `1Y`, `ALL`)
• `--tasks`: Update task checklist in issue body
• `--comment`: Post progress comment (default)
• `--labels`: Update issue labels based on status
• `--force`: Force sync even if up-to-date
• `--direction`: Sync direction (`to-github`, `from-github`, `two-way` - **default: two-way**)
• `--all`: Sync all active increments

Safety Options

• `--dry-run`: Preview changes without applying
• `--skip-rate-check`: Skip rate limit validation (not recommended)

Sync Direction

**Default: Two-way** (both directions)

SpecWeave syncs changes in **both directions** by default:

| Direction | What It Does | Use When | |-----------|-------------|----------| | **`two-way`** (default) | SpecWeave ↔ GitHub<br>• Pull changes FROM GitHub (status, labels, comments)<br>• Push changes TO GitHub (tasks, progress, metadata) | **Always** (recommended for keeping both systems in sync) | | `to-github` | SpecWeave → GitHub only<br>• Push increment progress to GitHub<br>• Don't pull GitHub changes back | Read-only GitHub usage, or when GitHub is downstream | | `from-github` | GitHub → SpecWeave only<br>• Pull GitHub issue updates<br>• Don't push SpecWeave changes | Importing GitHub issues, or when SpecWeave is downstream |

**Why Two-way?**

• ✅ Keep both systems synchronized automatically
• ✅ GitHub status changes update SpecWeave (closed issue → completed increment)
• ✅ SpecWeave task completion updates GitHub (task done → checklist updated)
• ✅ Team members can work in either tool
• ✅ No data loss from changes in either system

**Override if needed:**

# Push only (one-way to GitHub)
sw-github:sync 0004 --direction to-github

# Pull only (one-way from GitHub)
sw-github:sync 0004 --direction from-github

Examples

# Interactive two-way sync (default - both directions)
sw-github:sync 0004

# Use specific profile (still two-way by default)
sw-github:sync 0004 --profile specweave-dev

# Specify time range (two-way)
sw-github:sync 0004 --time-range 1M

# Full two-way sync with all options
sw-github:sync 0004 --profile main --time-range 1M --tasks --labels

# One-way sync examples (override default)
sw-github:sync 0004 --direction to-github     # Push only
sw-github:sync 0004 --direction from-github   # Pull only

# Dry run to preview changes
sw-github:sync 0004 --dry-run

# Force sync all increments (two-way)
sw-github:sync --all --force

Interactive Workflow

Step 1: Profile Selection

If multiple GitHub profiles exist, you'll be prompted to select one:

🔗 Select GitHub Profile

Available profiles:

  1. specweave-dev
     └─ 🐙 GitHub: anton-abyzov/specweave
     └─ Main SpecWeave repository
     └─ Default time range: 1 month (max: 6 months)

  2. another-repo
     └─ 🐙 GitHub: myorg/another-project
     └─ Another project repository
     └─ Default time range: 1 month (max: 6 months)

  3. ✨ Create new profile

Your choice: [1]

Step 2: Time Range Selection

Choose how far back to fetch GitHub data:

📅 Select Time Range for Sync

⚠️  IMPORTANT: Time range affects sync performance and rate limits

📅 GitHub Rate Limits:
   •