# GitHub Integration Strategy

## META
- created: 2026-02-14
- references: test-strategy.md, implementation-blueprint.md, AGENTS.md

## 1. REPOSITORY STRUCTURE

```
llmhost/                    # GitHub repo root
  .github/
    workflows/
      ci.yml                # Main CI pipeline
      release.yml           # Release pipeline  
      copilot-setup-steps.yml  # Copilot agent environment
      agentic-triage.yml    # Auto-triage issues
    ISSUE_TEMPLATE/
      bug_report.yml
      feature_request.yml
      task.yml
    PULL_REQUEST_TEMPLATE.md
    copilot-instructions.md  # GitHub Copilot custom instructions
    instructions/
      testing.instructions.md
      architecture.instructions.md
  AGENTS.md                 # AI agent instructions (Copilot, Claude, Cursor)
  CONTEXT.md                # SurfContext ARDS v2.0 for universal AI tools
  src/llmhosts/              # Python package source
  tests/                    # Test suite (per test-strategy.md)
  docs/                     # Documentation (migrated from current docs/)
  pyproject.toml
  Dockerfile
  docker-compose.yml
  CHANGELOG.md
  LICENSE                   # MIT
```

## 2. BRANCH STRATEGY

- **main**: always deployable, protected, requires PR + CI pass + 1 approval
- **develop**: integration branch for feature merges (optional, can use trunk-based)
- **feature/<issue-number>-<short-desc>**: feature branches from issues
- **fix/<issue-number>-<short-desc>**: bug fix branches
- **release/v<semver>**: release preparation branches
- **Recommendation**: trunk-based development with short-lived feature branches (AI agents work best with this)

## 3. CI/CD PIPELINE (GitHub Actions)

### ci.yml triggers: push to main, pull_request

**Jobs:**

1. **lint**: ruff check + ruff format --check + mypy
2. **test-unit**: pytest tests/unit/ --cov (parallel matrix: Python 3.11, 3.12)
3. **test-integration**: pytest tests/integration/ (needs Docker, uses testcontainers)
4. **test-contract**: schemathesis against openapi.yaml
5. **test-spec**: pytest tests/spec/ (spec validation)
6. **security**: bandit + safety + pip-audit
7. **build**: Build Docker image + Python wheel
8. **test-e2e**: pytest tests/e2e/ (full Docker Compose stack)

**Pipeline rules:**

- Unit + lint: run on every push/PR (<2 min)
- Integration + contract + spec: run on PR to main (<5 min)
- E2E + security: run on PR to main (<10 min)
- Performance: run on release branches only (manual trigger)
- All jobs use concurrency groups to cancel superseded runs

### release.yml triggers: tag v*

**Jobs:**

1. All CI jobs pass
2. Build wheel: python -m build
3. Publish to PyPI: twine upload
4. Build Docker: docker build + push to ghcr.io
5. Create GitHub Release with changelog
6. Notify: Slack/Discord webhook

### copilot-setup-steps.yml

```yaml
name: Copilot Setup
on: workflow_dispatch
jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -e ".[dev,test]"
      - run: docker pull ollama/ollama:latest  # for integration tests
```

## 4. ISSUE-DRIVEN DEVELOPMENT

### Issue Types:

- **Epic**: Large feature (maps to backlog epics), label: `epic`
- **Feature**: Single PRD feature, label: `feature`, links to epic
- **Task**: Implementation step from blueprint, label: `task`, links to feature
- **Bug**: Defect report, label: `bug`
- **Tech Debt**: Refactoring, label: `tech-debt`

### Labels:

**Priority**: `P0-critical`, `P1-high`, `P2-medium`, `P3-low`

**Size**: `XS` (<1h), `S` (1-4h), `M` (4-8h), `L` (1-2d), `XL` (2-5d)

**Agent**: `agent-ready` (can be assigned to Copilot), `needs-human`

**Phase**: `phase-1-core`, `phase-2-smart`, `phase-3-tunnel`, `phase-4-hive`

**Component**: `comp-router`, `comp-cache`, `comp-proxy`, `comp-cli`, `comp-dashboard`, `comp-tunnel`

### Workflow:

1. Create issue from template (or Copilot triages automatically)
2. Label with priority, size, component, phase
3. If `agent-ready`: assign to Copilot coding agent -> auto-creates PR
4. If `needs-human`: assign to developer
5. PR triggers CI -> review -> merge -> closes issue
6. GitHub Projects board auto-updates

## 5. GITHUB PROJECTS (Backlog Board)

**Board columns**: Backlog | Ready | In Progress | In Review | Done

**Views**: By Phase, By Component, By Priority, Sprint (2-week)

**Automation**: 
- New issue -> Backlog
- PR linked -> In Progress
- PR approved -> In Review
- PR merged -> Done
- Stale issues (30d) -> flagged for triage

## 6. PR CONVENTIONS

**Title**: `type(scope): description (#issue)`

Examples: 
- `feat(router): add kNN tier routing (#42)`
- `fix(cache): correct FP rate calculation (#87)`

**Body**: Use PR template with: Summary, Changes, Test Plan, Screenshots (if UI)

**Reviews**: Require 1 approval + all CI green

**Auto-merge**: Enable for `agent-ready` PRs that pass all checks

## 7. RELEASE MANAGEMENT

**Versioning**: Semantic Versioning (semver) - MAJOR.MINOR.PATCH
- **PATCH**: bug fixes, no API changes
- **MINOR**: new features, backward compatible
- **MAJOR**: breaking changes

**CHANGELOG**: Keep-a-Changelog format, auto-generated from PR titles

**Release cadence**: Every 2 weeks (sprint boundary) or as needed for critical fixes

**Artifacts**: PyPI package + Docker image (ghcr.io/llmhost/llmhost) + GitHub Release

## 8. SYNC PROTOCOL

GitHub as single source of truth means:

- All code lives in repo (no external repos)
- All docs live in repo `docs/` (no external wikis)
- All issues/tasks live in GitHub Issues (no external Jira)
- All discussions in GitHub Discussions (no external Slack channels for decisions)
- All CI/CD in GitHub Actions (no external Jenkins)
- Config-as-code: `.github/` directory defines all automation
- Infrastructure-as-code: Dockerfile + docker-compose.yml define deployment
- Every decision recorded as: ADR (architecture) or Issue comment (implementation)
- Weekly sync: automated report of open issues, PR velocity, test coverage trend

## 9. AI AGENT INTEGRATION

**AGENTS.md**: lives at repo root, instructs all AI agents (Copilot, Claude, Cursor)
- Coding conventions
- Test requirements (every PR must have tests)
- Architecture constraints
- File organization rules

**.github/copilot-instructions.md**: GitHub Copilot-specific instructions
- How to run tests
- How to build
- Which files to modify for which features

**copilot-setup-steps.yml**: environment setup for Copilot agent
- Python 3.12 + all dev dependencies pre-installed
- Docker available for integration tests

**GitHub Agentic Workflows** (when GA):
- Auto-triage: classify and label new issues
- Auto-review: code review suggestions on PRs
- Auto-docs: update docs when code changes

## 10. SECURITY

- Branch protection on `main`: require PR, CI pass, no force push
- Dependabot enabled for Python dependencies
- Secret scanning enabled
- Code scanning (CodeQL) enabled for Python
- CODEOWNERS file: require specific reviewers for sensitive paths
- Signed commits encouraged (not required initially)

## 11. METRICS AND VISIBILITY

**GitHub Insights**: PR merge time, issue close time, CI pass rate

**Custom dashboard** (GitHub Actions + GitHub API):
- Test coverage trend (badge in README)
- Open issue count by priority
- Sprint velocity (issues closed per sprint)
- Release frequency
- Mean time to merge
