MQL5-Google-Onedrive/docs/GITHUB_PAGES_SYNC_SETUP.md

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:

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
• Cloud Deployment Guide