mirror of
https://github.com/samerfarida/mcp-ssh-orchestrator.git
synced 2026-11-20 12:23:31 +00:00
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:
@@ -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: |
|
||||
|
||||
@@ -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
|
||||
Executable
+99
@@ -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"
|
||||
Reference in New Issue
Block a user