forked from LengKundee/MQL5-Google-Onedrive
335a79e43d
- Replace GITHUB_TOKEN with PAGES_SYNC_TOKEN for external repo access - Add graceful degradation when token is not configured - Add setup documentation in GITHUB_PAGES_SYNC_SETUP.md - Update GITHUB_CI_CD_SETUP.md with token configuration steps Co-authored-by: Mouy-leng <199350297+Mouy-leng@users.noreply.github.com>
117 lines
3.6 KiB
Markdown
117 lines
3.6 KiB
Markdown
# GitHub Pages Sync Configuration
|
|
|
|
This document explains how to configure the automatic sync to GitHub Pages.
|
|
|
|
## Overview
|
|
|
|
The `github-pages-sync.yml` workflow automatically syncs MQL5 files, documentation, and README to an external GitHub Pages repository whenever changes are pushed to the main branch.
|
|
|
|
## Configuration
|
|
|
|
### 1. Set Up Personal Access Token
|
|
|
|
The workflow requires a Personal Access Token (PAT) to push to the external GitHub Pages repository.
|
|
|
|
**Why is this needed?**
|
|
- The default `GITHUB_TOKEN` provided by GitHub Actions only has permissions for the current repository
|
|
- To push to another repository (like a GitHub Pages repo), you need a PAT with `repo` scope
|
|
|
|
**Steps to create PAT:**
|
|
|
|
1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
|
|
- URL: https://github.com/settings/tokens
|
|
2. Click **Generate new token (classic)**
|
|
3. Give it a descriptive name: `GitHub Pages Sync Token`
|
|
4. Select scopes:
|
|
- ✅ `repo` (Full control of private repositories)
|
|
5. Set expiration (recommend 90 days or 1 year)
|
|
6. Click **Generate token**
|
|
7. **Copy the token immediately** (you won't be able to see it again)
|
|
|
|
### 2. Add Token as Repository Secret
|
|
|
|
1. Go to your repository → **Settings** → **Secrets and variables** → **Actions**
|
|
2. Click **New repository secret**
|
|
3. Name: `PAGES_SYNC_TOKEN`
|
|
4. Value: Paste the PAT you created
|
|
5. Click **Add secret**
|
|
|
|
### 3. Configure Target Repository
|
|
|
|
The target repository is configured in the workflow file:
|
|
|
|
```yaml
|
|
env:
|
|
PAGES_REPO: Mouy-leng/-LengKundee-mql5.github.io.git
|
|
PAGES_BRANCH: main
|
|
```
|
|
|
|
To change the target repository, edit `.github/workflows/github-pages-sync.yml`.
|
|
|
|
## Behavior
|
|
|
|
### With Token Configured
|
|
When `PAGES_SYNC_TOKEN` is configured:
|
|
1. ✅ Workflow checks out the main repository
|
|
2. ✅ Clones the GitHub Pages repository
|
|
3. ✅ Syncs MQL5 files to `mql5/` directory
|
|
4. ✅ Syncs documentation to `docs/` directory
|
|
5. ✅ Copies README.md
|
|
6. ✅ Commits and pushes changes
|
|
7. ✅ Shows success summary
|
|
|
|
### Without Token Configured
|
|
When `PAGES_SYNC_TOKEN` is not configured:
|
|
1. ⚠️ Workflow detects missing token
|
|
2. ⚠️ Logs: "Skipping GitHub Pages sync: PAGES_SYNC_TOKEN not configured"
|
|
3. ✅ Workflow exits gracefully with success (does not fail)
|
|
4. ✅ No error in CI/CD pipeline
|
|
|
|
## Triggering the Sync
|
|
|
|
The sync is triggered automatically on:
|
|
- Push to `main` branch
|
|
- Changes to:
|
|
- `mt5/MQL5/**`
|
|
- `docs/**`
|
|
- `README.md`
|
|
- `.github/workflows/github-pages-sync.yml`
|
|
|
|
Manual trigger:
|
|
- Go to **Actions** tab → **Sync to GitHub Pages** → **Run workflow**
|
|
|
|
## Troubleshooting
|
|
|
|
### Error: "could not read Password"
|
|
**Symptom:**
|
|
```
|
|
fatal: could not read Password for 'https://***@github.com': No such device or address
|
|
```
|
|
|
|
**Solution:** The `PAGES_SYNC_TOKEN` secret is not configured. Follow the setup steps above.
|
|
|
|
### Error: "Permission denied"
|
|
**Symptom:** Push fails with permission denied error
|
|
|
|
**Solution:**
|
|
1. Verify the PAT has `repo` scope
|
|
2. Ensure the PAT hasn't expired
|
|
3. Check that the target repository exists and you have write access
|
|
|
|
### Sync is skipped
|
|
**Symptom:** Workflow logs show "Skipping GitHub Pages sync"
|
|
|
|
**Solution:** This is expected if `PAGES_SYNC_TOKEN` is not configured. The workflow will skip gracefully without failing.
|
|
|
|
## Security Notes
|
|
|
|
- ✅ Token is stored as a secret and never exposed in logs
|
|
- ✅ Token is masked in workflow outputs (`***`)
|
|
- ✅ Only repository admins can view/edit secrets
|
|
- ✅ Rotate token periodically for security
|
|
- ⚠️ Never commit the token to the repository
|
|
|
|
## Related Documentation
|
|
|
|
- [GitHub CI/CD Setup](./GITHUB_CI_CD_SETUP.md)
|
|
- [Cloud Deployment Guide](./CLOUD_DEPLOYMENT.md)
|