diff --git a/.github/workflows/sync-wiki.yml b/.github/workflows/sync-wiki.yml index 5b7ebb3..87be43d 100644 --- a/.github/workflows/sync-wiki.yml +++ b/.github/workflows/sync-wiki.yml @@ -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: | diff --git a/GITHUB_ACTIONS_TROUBLESHOOTING.md b/GITHUB_ACTIONS_TROUBLESHOOTING.md new file mode 100644 index 0000000..e6a91ee --- /dev/null +++ b/GITHUB_ACTIONS_TROUBLESHOOTING.md @@ -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 diff --git a/manual-wiki-sync.sh b/manual-wiki-sync.sh new file mode 100755 index 0000000..72c925f --- /dev/null +++ b/manual-wiki-sync.sh @@ -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"