# GitHub Pages Setup for Performance Dashboard

**Purpose**: Enable GitHub Pages to host the performance dashboard generated by github-action-benchmark.

**Decision**: ADR-0007 - Daily Performance Monitoring on CI/CD

---

## Prerequisites

- Repository: `terrylica/rangebar-py`
- Workflows: `.github/workflows/performance-daily.yml`, `.github/workflows/performance-weekly.yml`
- GitHub permissions: Repository settings access

---

## Setup Steps

### Step 1: Enable GitHub Pages

1. Navigate to: https://github.com/terrylica/rangebar-py/settings/pages
2. Under "Build and deployment":
   - **Source**: GitHub Actions
3. Click **Save**

**Note**: The workflow will handle deployment automatically via `actions/deploy-pages@v4`. No need to configure branch or folder.

### Step 2: Verify Configuration

After the first workflow run (either manual trigger or daily cron):

1. Check `gh-pages` branch exists:

   ```bash
   git fetch origin gh-pages
   git checkout gh-pages
   ls -la dev/bench/
   ```

2. Verify JSON files:

   ```bash
   cat dev/bench/python-bench.json | jq '.benchmarks[] | {name: .name, mean: .stats.mean}'
   ```

3. Wait 2-3 minutes for GitHub Pages deployment

4. Open dashboard: https://terrylica.github.io/rangebar-py/

### Step 3: Trigger Initial Workflow

If the `gh-pages` branch doesn't exist yet, manually trigger the workflow:

```bash
gh workflow run performance-daily.yml
gh run watch
```

This will:

1. Run benchmarks
2. Generate `python-bench.json`
3. Create `gh-pages` branch (if not exists)
4. Commit JSON + HTML dashboard to `gh-pages`
5. GitHub Pages auto-deploys dashboard

---

## Troubleshooting

### Dashboard shows "404 Not Found"

**Cause**: GitHub Pages not enabled or workflow hasn't deployed yet

**Fix**:

1. Go to: https://github.com/terrylica/rangebar-py/settings/pages
2. Verify "Source" is set to "GitHub Actions"
3. Check workflow has run successfully:
   ```bash
   gh run list --workflow=performance-daily.yml
   ```
4. Check "Pages" section shows: "Your site is live at https://terrylica.github.io/rangebar-py/"

### `gh-pages` branch doesn't exist

**Cause**: Workflow hasn't run yet, or `auto-push: true` failed

**Fix**:

1. Manually trigger workflow:

   ```bash
   gh workflow run performance-daily.yml
   ```

2. Check workflow logs:

   ```bash
   gh run list --workflow=performance-daily.yml
   gh run view --log
   ```

3. Look for errors in "Store Python benchmark results" step

**Note**: With GitHub Actions deployment, the `gh-pages` branch is still created by github-action-benchmark for data storage, but deployment is handled by the workflow explicitly.

### Workflow runs but dashboard not updated

**Cause**: Permission error or deployment step failed

**Fix**:

1. Verify workflow has all required permissions:

   ```yaml
   permissions:
     contents: write # Required for github-action-benchmark
     pages: write # Required for GitHub Pages deployment
     id-token: write # Required for OIDC token
   ```

2. Check workflow logs for "Deploy to GitHub Pages" step errors

3. Verify environment is configured:

   ```yaml
   environment:
     name: github-pages
     url: ${{ steps.deployment.outputs.page_url }}
   ```

4. If error persists, check repository settings:
   - Settings → Actions → General → Workflow permissions
   - Ensure "Read and write permissions" is selected

### Dashboard shows old data

**Cause**: Browser cache or GitHub Pages deployment delay

**Fix**:

1. Hard refresh browser: `Cmd+Shift+R` (macOS) or `Ctrl+Shift+R` (Linux/Windows)
2. Wait 2-3 minutes for GitHub Pages deployment
3. Check `gh-pages` branch commit history:
   ```bash
   git fetch origin gh-pages
   git log origin/gh-pages --oneline -5
   ```

---

## Verification Checklist

After setup, verify:

- [ ] GitHub Pages source set to "GitHub Actions" at https://github.com/terrylica/rangebar-py/settings/pages
- [ ] Workflow has run successfully (check Actions tab)
- [ ] `gh-pages` branch exists and has commits (data storage)
- [ ] Dashboard accessible at https://terrylica.github.io/rangebar-py/
- [ ] Deployment appears in Actions tab under "pages build and deployment"
- [ ] Chart.js graphs render correctly
- [ ] Benchmark data points visible in graphs
- [ ] JSON files accessible (e.g., https://terrylica.github.io/rangebar-py/dev/bench/python-bench.json)

---

## Maintenance

**Zero maintenance required** - GitHub Pages and github-action-benchmark handle:

- Automatic dashboard updates (every workflow run)
- Historical data retention (unlimited on GitHub Pages)
- Regression detection (150% threshold)
- Chart.js visualization updates

**Only manual intervention needed if**:

- Repository renamed (update dashboard URL in README.md)
- GitHub Pages disabled accidentally (re-enable in settings)
- Workflow permissions revoked (restore `contents: write`)

---

## References

- **ADR**: `docs/decisions/0007-daily-performance-monitoring.md`
- **Plan**: `docs/plan/0007-daily-performance-monitoring/plan.md`
- **Workflows**: `.github/workflows/performance-daily.yml`, `.github/workflows/performance-weekly.yml`
- **CLAUDE.md**: Daily Performance Monitoring section

**GitHub Actions**:

- Workflow runs: https://github.com/terrylica/rangebar-py/actions/workflows/performance-daily.yml
- GitHub Pages settings: https://github.com/terrylica/rangebar-py/settings/pages

**External Docs**:

- github-action-benchmark: https://github.com/benchmark-action/github-action-benchmark#usage
- GitHub Pages: https://docs.github.com/en/pages/getting-started-with-github-pages
