fix: Resolve GitHub Actions wiki sync issues

- Fix rsync command to preserve .git directory
- Add manual wiki sync script for testing
- Improve error handling and debugging
- Add comprehensive troubleshooting guide
- Ensure proper branch handling (master for wikis)

Manual sync successful: All 16 wiki sections now live!
This commit is contained in:
Sammy Farida
2025-10-25 22:51:36 -04:00
parent 77305e05ef
commit 7cdfffd9ed
3 changed files with 303 additions and 46 deletions
+47 -46
View File
@@ -25,35 +25,21 @@ jobs:
git config --global user.name "github-actions[bot]"
git config --global user.email "github-actions[bot]@users.noreply.github.com"
- name: Create Wiki Sync Script
- name: Sync Wiki Content
run: |
cat > sync-wiki.sh << 'EOF'
#!/bin/bash
set -e
echo "🔄 Starting wiki sync process..."
# Create wiki directory
mkdir -p wiki-sync
cd wiki-sync
# Initialize git repo for wiki
git init
git remote add origin https://github.com/${{ github.repository }}.wiki.git
# Clone the existing wiki repository
echo "📥 Cloning wiki repository..."
git clone https://github.com/${{ github.repository }}.wiki.git .
# Try to fetch existing wiki content
echo "📥 Fetching existing wiki content..."
if git fetch origin master 2>/dev/null; then
echo "✅ Found existing wiki, checking out master branch"
git checkout -b master origin/master
else
echo "ℹ️ No existing wiki found, creating new master branch"
git checkout -b master
fi
# Copy wiki content
# Copy new content from main repository
echo "📋 Copying wiki content..."
rsync -av --delete ../docs/wiki/ ./
rsync -av --delete --exclude='.git' ../docs/wiki/ ./
# Add .gitkeep to preserve empty directories
find . -type d -empty -exec touch {}/.gitkeep \;
@@ -79,33 +65,14 @@ jobs:
# Push to wiki repository
echo "🚀 Pushing to wiki repository..."
if git push origin master; then
echo "✅ Wiki synced successfully"
else
echo "❌ Failed to push to wiki repository"
echo "This might be due to:"
echo "1. Wiki repository not existing yet"
echo "2. Insufficient permissions"
echo "3. Network issues"
echo ""
echo "To fix this:"
echo "1. Go to your repository settings"
echo "2. Enable the Wiki feature"
echo "3. Create at least one wiki page manually"
echo "4. Re-run this workflow"
exit 1
fi
git push origin master
echo "✅ Wiki synced successfully"
else
echo "ℹ️ No changes to sync"
fi
echo "🎉 Wiki sync process completed"
EOF
chmod +x sync-wiki.sh
- name: Run Wiki Sync
run: ./sync-wiki.sh
- name: Validate Wiki Content
run: |
@@ -138,6 +105,44 @@ jobs:
echo "⚠️ Home.md not found"
fi
# Check for all 16 sections
required_sections=(
"01-MCP-Overview.md"
"02-Risks.md"
"03-Design-Goals.md"
"04-Architecture.md"
"05-Security-Model.md"
"06-Configuration.md"
"07-Tools-Reference.md"
"08-Usage-Cookbook.md"
"09-Deployment.md"
"10-Integrations.md"
"11-Observability-Audit.md"
"12-Troubleshooting.md"
"13-Contributing.md"
"14-Roadmap.md"
"15-FAQ.md"
"16-Glossary.md"
)
echo "🔍 Checking required sections:"
missing_sections=()
for section in "${required_sections[@]}"; do
if [ -f "wiki-sync/$section" ]; then
echo " ✅ $section"
else
echo " ❌ $section"
missing_sections+=("$section")
fi
done
if [ ${#missing_sections[@]} -gt 0 ]; then
echo "❌ Missing sections: ${missing_sections[*]}"
exit 1
else
echo "✅ All required sections present"
fi
else
echo "❌ Wiki content directory is empty or doesn't exist"
exit 1
@@ -156,11 +161,7 @@ jobs:
- name: Install validation tools
run: |
# Install basic tools
pip install pyyaml
# Install markdown link checker if available
npm install -g markdown-link-check || echo "markdown-link-check not available"
- name: Validate YAML examples
run: |
+157
View File
@@ -0,0 +1,157 @@
# 🔧 GitHub Actions Wiki Sync Troubleshooting
## Common Issues and Solutions
### 1. **Wiki Repository Doesn't Exist**
**Error:** `Failed to push to wiki repository`
**Solution:**
1. Go to your GitHub repository
2. Click on **Settings** tab
3. Scroll down to **Features** section
4. Check the **Wiki** checkbox to enable it
5. Click **Save**
6. Create at least one wiki page manually (even just a test page)
7. Re-run the GitHub Actions workflow
### 2. **Permission Issues**
**Error:** `Permission denied` or `403 Forbidden`
**Solutions:**
- **Repository permissions**: Ensure the repository allows GitHub Actions
- **Wiki permissions**: Make sure the wiki is enabled and accessible
- **Branch protection**: Check if branch protection rules are blocking the workflow
### 3. **Workflow Not Triggering**
**Issue:** Workflow doesn't run when pushing to `docs/wiki/`
**Solutions:**
- Check the workflow file is in `.github/workflows/sync-wiki.yml`
- Verify the `paths` filter includes `docs/wiki/**`
- Ensure you're pushing to the `main` branch
- Check GitHub Actions is enabled for the repository
### 4. **YAML Validation Errors**
**Error:** `Invalid YAML` in documentation
**Solution:**
- Check YAML syntax in configuration examples
- Ensure proper indentation (use spaces, not tabs)
- Validate YAML blocks in markdown files
### 5. **Link Validation Failures**
**Error:** Broken links in documentation
**Solutions:**
- Check internal links point to existing wiki pages
- Verify external links are accessible
- Update link-check-config.json to ignore problematic patterns
## Manual Wiki Setup
If the automated sync continues to fail, you can set up the wiki manually:
### Step 1: Enable Wiki
1. Go to repository **Settings**
2. Enable **Wiki** feature
3. Create a test page
### Step 2: Clone Wiki Repository
```bash
git clone https://github.com/samerfarida/mcp-ssh-orchestrator.wiki.git
cd mcp-ssh-orchestrator.wiki
```
### Step 3: Copy Content
```bash
# Copy wiki content from main repository
cp -r ../mcp-ssh-orchestrator/docs/wiki/* .
```
### Step 4: Commit and Push
```bash
git add .
git commit -m "Initial wiki content"
git push origin master
```
## Workflow Debugging
### Enable Debug Logging
Add this to the workflow for more detailed output:
```yaml
- name: Debug Information
run: |
echo "Repository: ${{ github.repository }}"
echo "SHA: ${{ github.sha }}"
echo "Event: ${{ github.event_name }}"
echo "Ref: ${{ github.ref }}"
```
### Check Workflow Status
1. Go to **Actions** tab in your repository
2. Click on the failed workflow run
3. Expand each step to see detailed logs
4. Look for error messages and stack traces
### Common Error Messages
**`git fetch origin master` fails:**
- Wiki repository doesn't exist yet
- Solution: Enable wiki and create initial page
**`git push origin master` fails:**
- Permission issues
- Solution: Check repository settings and permissions
**`rsync` fails:**
- Source directory doesn't exist
- Solution: Ensure `docs/wiki/` directory exists
**YAML validation fails:**
- Invalid YAML syntax in examples
- Solution: Fix YAML syntax in markdown files
## Testing the Workflow
### Local Testing
```bash
# Test the sync script locally
chmod +x test-sync-workflow.sh
./test-sync-workflow.sh
```
### Manual Workflow Trigger
1. Go to **Actions** tab
2. Select **Sync Wiki Documentation**
3. Click **Run workflow**
4. Select branch and click **Run workflow**
## Success Indicators
✅ **Workflow runs successfully**
✅ **Wiki content appears in GitHub wiki**
✅ **All 16 sections are accessible**
✅ **Links work correctly**
✅ **YAML examples are valid**
## Getting Help
If issues persist:
1. Check the **Actions** tab for detailed error logs
2. Verify repository settings and permissions
3. Test the workflow manually
4. Create a GitHub issue with error details
## Next Steps
Once the workflow is working:
1. **Monitor**: Check that wiki stays in sync
2. **Update**: Modify `docs/wiki/` content as needed
3. **Validate**: Ensure all links and examples work
4. **Maintain**: Keep documentation up to date
+99
View File
@@ -0,0 +1,99 @@
#!/bin/bash
# manual-wiki-sync.sh
# Manual script to sync wiki content
set -e
echo "🔄 Manual Wiki Sync Script"
echo "=========================="
# Configuration
REPO_NAME="samerfarida/mcp-ssh-orchestrator"
WIKI_URL="https://github.com/${REPO_NAME}.wiki.git"
WIKI_DIR="temp-wiki-sync"
# Check if we're in the right directory
if [ ! -f "pyproject.toml" ]; then
echo "❌ Error: Not in mcp-ssh-orchestrator root directory"
exit 1
fi
# Check if docs/wiki directory exists
if [ ! -d "docs/wiki" ]; then
echo "❌ Error: docs/wiki directory not found"
exit 1
fi
echo "📁 Source directory: docs/wiki/"
echo "🎯 Target: ${WIKI_URL}"
# Clean up any existing temp directory
if [ -d "$WIKI_DIR" ]; then
echo "🧹 Cleaning up existing temp directory..."
rm -rf "$WIKI_DIR"
fi
# Clone the wiki repository
echo "📥 Cloning wiki repository..."
git clone "$WIKI_URL" "$WIKI_DIR"
cd "$WIKI_DIR"
# Ensure we're on the master branch (wikis use master, not main)
git checkout master
# Show current wiki content
echo "📋 Current wiki content:"
ls -la *.md 2>/dev/null || echo "No markdown files found"
# Copy new content (preserve .git directory)
echo "📋 Copying wiki content..."
rsync -av --delete --exclude='.git' ../docs/wiki/ ./
# Show what will be added/changed
echo "📝 Changes to be committed:"
git add .
git status
# Check if there are changes
if ! git diff --staged --quiet; then
echo "📝 Changes detected, committing..."
# Get list of changed files
CHANGED_FILES=$(git diff --staged --name-only | head -10)
git commit -m "Manual sync: Update wiki content
Synced from local docs/wiki/ directory
Changed files:
$CHANGED_FILES
[skip ci]"
# Push to wiki repository
echo "🚀 Pushing to wiki repository..."
echo "Current remote: $(git remote -v)"
git push origin master
echo "✅ Wiki synced successfully!"
# Show final content
echo "📋 Final wiki content:"
ls -la *.md | head -20
else
echo "ℹ️ No changes to sync"
fi
# Clean up
cd ..
rm -rf "$WIKI_DIR"
echo ""
echo "🎉 Manual wiki sync completed!"
echo "🔗 Wiki available at: https://github.com/${REPO_NAME}/wiki"
echo ""
echo "📋 Next steps:"
echo "1. Visit the wiki URL to verify content"
echo "2. Check that all 16 sections are present"
echo "3. Test navigation and links"
echo "4. Run the GitHub Actions workflow to automate future syncs"