# GitHub Pages Deployment Method - Token List

**Date**: $(date)  
**Question**: GitHub Actions or Deploy from a branch?

---

## 📊 Comparison

### Option 1: Deploy from a branch ✅ **RECOMMENDED**

**How it works**:
- GitHub Pages serves files directly from a branch
- No build process needed
- Automatic deployment on push

**Best for**:
- ✅ Static files (JSON, HTML, CSS, JS)
- ✅ Simple projects
- ✅ No build steps required
- ✅ **Token lists** (like yours)

**Pros**:
- ✅ Simple setup (one click)
- ✅ Fast deployment (1-2 minutes)
- ✅ No configuration needed
- ✅ Automatic updates on push
- ✅ No GitHub Actions minutes used

**Cons**:
- ❌ No custom build steps
- ❌ No preprocessing

---

### Option 2: GitHub Actions

**How it works**:
- Custom workflow runs on push
- Can build, validate, transform files
- Deploys to GitHub Pages

**Best for**:
- Complex builds (Jekyll, Next.js, etc.)
- Custom validation steps
- File transformation
- Multiple deployment targets

**Pros**:
- ✅ Full control over build process
- ✅ Can validate JSON before deploy
- ✅ Can transform/optimize files
- ✅ Custom deployment logic

**Cons**:
- ❌ More complex setup
- ❌ Requires workflow file
- ❌ Uses GitHub Actions minutes
- ❌ Overkill for simple JSON files

---

## ✅ Recommendation: **Deploy from a branch**

For your token list (`config/token-list.json`), **deploying from a branch is the best choice** because:

1. **Simple**: Just a JSON file, no build needed
2. **Fast**: Immediate deployment
3. **Reliable**: No build failures to worry about
4. **Cost-effective**: No Actions minutes used
5. **Standard**: Most token lists use this method

---

## 🚀 Setup Instructions

### Step 1: Choose "Deploy from a branch"

In GitHub Pages settings:
1. Under **"Build and deployment"** → **"Source"**
2. Select: **"Deploy from a branch"** (not "GitHub Actions")
3. **Branch**: Select `main`
4. **Folder**: Select `/ (root)`
5. Click **Save**

### Step 2: Verify

After saving:
- GitHub Pages will deploy automatically
- Check **Actions** tab (should show "pages build and deployment")
- Wait 1-2 minutes
- Token list will be live at:
  ```
  https://defi-oracle-meta-blockchain.github.io/metamask-integration/config/token-list.json
  ```

---

## 🔄 When to Use GitHub Actions Instead

Consider GitHub Actions if you need:

1. **JSON Validation**:
   ```yaml
   - name: Validate token list
     run: |
       cat config/token-list.json | jq .
   ```

2. **Version Checking**:
   ```yaml
   - name: Check version increment
     run: |
       # Ensure version number increased
   ```

3. **Multiple Formats**:
   ```yaml
   - name: Generate multiple formats
     run: |
       # Create .json, .json5, etc.
   ```

4. **Custom Headers**:
   ```yaml
   - name: Add custom headers
     run: |
       # Set CORS, cache headers
   ```

**For your current use case**: None of these are necessary. The JSON file is valid, and GitHub Pages handles CORS automatically.

---

## 📋 Current Setup

**Your Token List**:
- **File**: `config/token-list.json`
- **Type**: Static JSON
- **Size**: Small (~1KB)
- **Updates**: Manual (when you push changes)

**Recommended Method**: ✅ **Deploy from a branch**

---

## 🎯 Quick Decision Guide

| Need | Use Branch | Use Actions |
|------|------------|-------------|
| Static JSON file | ✅ Yes | ❌ Overkill |
| Simple HTML/CSS | ✅ Yes | ❌ Overkill |
| Jekyll site | ⚠️ Either | ✅ Better |
| Custom build steps | ❌ No | ✅ Yes |
| JSON validation | ⚠️ Optional | ✅ Better |
| Multiple formats | ❌ No | ✅ Yes |

**Your case**: Static JSON → ✅ **Use Branch**

---

## ✅ Final Recommendation

**Choose**: **"Deploy from a branch"**

**Configuration**:
- Source: **Deploy from a branch**
- Branch: **main**
- Folder: **/ (root)**

**Result**: Simple, fast, reliable token list hosting.

---

## 🔄 Future: If You Need Actions

If you later want to add validation or custom steps, you can:

1. Create `.github/workflows/pages.yml`:
   ```yaml
   name: Deploy Pages
   on:
     push:
       branches: [main]
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - name: Validate JSON
           run: cat config/token-list.json | jq .
         - name: Deploy
           uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./
   ```

2. Change Pages source to **"GitHub Actions"**

**But for now**: Stick with branch deployment. ✅

---

## 📚 Related Documentation

- [GitHub Pages Setup Guide](../metamask-integration/docs/GITHUB_PAGES_SETUP.md)
- [Token List Hosting Guide](./METAMASK_TOKEN_LIST_HOSTING.md)

---

**Last Updated**: $(date)

