aitbc/.windsurf/workflows/github.md

description, title, version, auto_execution_mode

description	title	version	auto_execution_mode
Comprehensive GitHub operations including git push to GitHub with multi-node synchronization	AITBC GitHub Operations Workflow	2.1	3

AITBC GitHub Operations Workflow

This workflow handles all GitHub operations including staging, committing, and pushing changes to GitHub repository with multi-node synchronization capabilities. It ensures both genesis and follower nodes maintain consistent git status after GitHub operations.

Prerequisites

Required Setup

• GitHub repository configured as remote
• GitHub access token available
• Git user configured
• Working directory: /opt/aitbc

Environment Setup

cd /opt/aitbc
git status
git remote -v

GitHub Operations Workflow

1. Check Current Status

# Check git status
git status

# Check remote configuration
git remote -v

# Check current branch
git branch

# Check for uncommitted changes
git diff --stat

2. Stage Changes

# Stage all changes
git add .

# Stage specific files
git add docs/ cli/ scripts/

# Stage specific directory
git add .windsurf/

# Check staged changes
git status --short

3. Commit Changes

# Commit with descriptive message
git commit -m "feat: update CLI documentation and workflows

- Updated CLI enhancement workflow to reflect current structure
- Added comprehensive GitHub operations workflow
- Updated documentation paths and service endpoints
- Enhanced CLI command documentation"

# Commit with specific changes
git commit -m "fix: resolve service endpoint issues

- Updated coordinator API port from 18000 to 8000
- Fixed blockchain RPC endpoint configuration
- Updated CLI commands to use correct service ports"

# Quick commit for minor changes
git commit -m "docs: update README with latest changes"

4. Push to GitHub

# Push to main branch
git push origin main

# Push to specific branch
git push origin develop

# Push with upstream tracking (first time)
git push -u origin main

# Force push (use with caution)
git push --force-with-lease origin main

# Push all branches
git push --all origin

5. Multi-Node Git Status Check

# Check git status on both nodes
echo "=== Genesis Node Git Status ==="
cd /opt/aitbc
git status
git log --oneline -3

echo ""
echo "=== Follower Node Git Status ==="
ssh aitbc1 'cd /opt/aitbc && git status'
ssh aitbc1 'cd /opt/aitbc && git log --oneline -3'

echo ""
echo "=== Comparison Check ==="
# Get latest commit hashes
GENESIS_HASH=$(git rev-parse HEAD)
FOLLOWER_HASH=$(ssh aitbc1 'cd /opt/aitbc && git rev-parse HEAD')

echo "Genesis latest: $GENESIS_HASH"
echo "Follower latest: $FOLLOWER_HASH"

if [ "$GENESIS_HASH" = "$FOLLOWER_HASH" ]; then
    echo "✅ Both nodes are in sync"
else
    echo "⚠️ Nodes are out of sync"
    echo "Genesis ahead by: $(git rev-list --count $FOLLOWER_HASH..HEAD 2>/dev/null || echo "N/A") commits"
    echo "Follower ahead by: $(ssh aitbc1 'cd /opt/aitbc && git rev-list --count $GENESIS_HASH..HEAD 2>/dev/null || echo "N/A"') commits"
fi

6. Sync Follower Node (if needed)

# Sync follower node with genesis
if [ "$GENESIS_HASH" != "$FOLLOWER_HASH" ]; then
    echo "=== Syncing Follower Node ==="
    
    # Option 1: Push from genesis to follower
    ssh aitbc1 'cd /opt/aitbc && git fetch origin'
    ssh aitbc1 'cd /opt/aitbc && git pull origin main'
    
    # Option 2: Copy changes directly (if remote sync fails)
    rsync -av --exclude='.git' /opt/aitbc/ aitbc1:/opt/aitbc/
    ssh aitbc1 'cd /opt/aitbc && git add . && git commit -m "sync from genesis node" || true'
    
    echo "✅ Follower node synced"
fi

7. Verify Push

# Check if push was successful
git status

# Check remote status
git log --oneline -5 origin/main

# Verify on GitHub (if GitHub CLI is available)
gh repo view --web

# Verify both nodes are updated
echo "=== Final Status Check ==="
echo "Genesis: $(git rev-parse --short HEAD)"
echo "Follower: $(ssh aitbc1 'cd /opt/aitbc && git rev-parse --short HEAD')"

Quick GitHub Commands

Multi-Node Standard Workflow

# Complete multi-node workflow - check, stage, commit, push, sync
cd /opt/aitbc

# 1. Check both nodes status
echo "=== Checking Both Nodes ==="
git status
ssh aitbc1 'cd /opt/aitbc && git status'

# 2. Stage and commit
git add .
git commit -m "feat: add new feature implementation"

# 3. Push to GitHub
git push origin main

# 4. Sync follower node
ssh aitbc1 'cd /opt/aitbc && git pull origin main'

# 5. Verify both nodes
echo "=== Verification ==="
git rev-parse --short HEAD
ssh aitbc1 'cd /opt/aitbc && git rev-parse --short HEAD'

Quick Multi-Node Push

# Quick push for minor changes with node sync
cd /opt/aitbc
git add . && git commit -m "docs: update documentation" && git push origin main
ssh aitbc1 'cd /opt/aitbc && git pull origin main'

Multi-Node Sync Check

# Quick sync status check
cd /opt/aitbc
GENESIS_HASH=$(git rev-parse HEAD)
FOLLOWER_HASH=$(ssh aitbc1 'cd /opt/aitbc && git rev-parse HEAD')
if [ "$GENESIS_HASH" = "$FOLLOWER_HASH" ]; then
    echo "✅ Both nodes in sync"
else
    echo "⚠️ Nodes out of sync - sync needed"
fi

Standard Workflow

# Complete workflow - stage, commit, push
cd /opt/aitbc
git add .
git commit -m "feat: add new feature implementation"
git push origin main

Quick Push

# Quick push for minor changes
git add . && git commit -m "docs: update documentation" && git push origin main

Specific File Push

# Push specific changes
git add docs/README.md
git commit -m "docs: update main README"
git push origin main

Advanced GitHub Operations

Branch Management

# Create new branch
git checkout -b feature/new-feature

# Switch branches
git checkout develop

# Merge branches
git checkout main
git merge feature/new-feature

# Delete branch
git branch -d feature/new-feature

Remote Management

# Add GitHub remote
git remote add github https://github.com/oib/AITBC.git

# Set up GitHub with token from secure file
GITHUB_TOKEN=$(cat /root/github_token)
git remote set-url github https://${GITHUB_TOKEN}@github.com/oib/AITBC.git

# Push to GitHub specifically
git push github main

# Push to both remotes
git push origin main && git push github main

Sync Operations

# Pull latest changes from GitHub
git pull origin main

# Sync with GitHub
git fetch origin
git rebase origin/main

# Push to GitHub after sync
git push origin main

Troubleshooting

Multi-Node Sync Issues

# Check if nodes are in sync
cd /opt/aitbc
GENESIS_HASH=$(git rev-parse HEAD)
FOLLOWER_HASH=$(ssh aitbc1 'cd /opt/aitbc && git rev-parse HEAD')

if [ "$GENESIS_HASH" != "$FOLLOWER_HASH" ]; then
    echo "⚠️ Nodes out of sync - fixing..."
    
    # Check connectivity to follower
    ssh aitbc1 'echo "Follower node reachable"' || {
        echo "❌ Cannot reach follower node"
        exit 1
    }
    
    # Sync follower node
    ssh aitbc1 'cd /opt/aitbc && git fetch origin'
    ssh aitbc1 'cd /opt/aitbc && git pull origin main'
    
    # Verify sync
    NEW_FOLLOWER_HASH=$(ssh aitbc1 'cd /opt/aitbc && git rev-parse HEAD')
    if [ "$GENESIS_HASH" = "$NEW_FOLLOWER_HASH" ]; then
        echo "✅ Nodes synced successfully"
    else
        echo "❌ Sync failed - manual intervention required"
    fi
fi

Push Failures

# Check if remote exists
git remote get-url origin

# Check authentication
git config --get remote.origin.url

# Fix authentication issues
GITHUB_TOKEN=$(cat /root/github_token)
git remote set-url origin https://${GITHUB_TOKEN}@github.com/oib/AITBC.git

# Force push if needed
git push --force-with-lease origin main

Merge Conflicts

# Check for conflicts
git status

# Resolve conflicts manually
# Edit conflicted files, then:
git add .
git commit -m "resolve merge conflicts"

# Abort merge if needed
git merge --abort

Remote Issues

# Check remote connectivity
git ls-remote origin

# Re-add remote if needed
git remote remove origin
git remote add origin https://github.com/oib/AITBC.git

# Test push
git push origin main --dry-run

GitHub Integration

GitHub CLI (if available)

# Create pull request
gh pr create --title "Update CLI documentation" --body "Comprehensive CLI documentation updates"

# View repository
gh repo view

# List issues
gh issue list

# Create release
gh release create v1.0.0 --title "Version 1.0.0" --notes "Initial release"

Web Interface

# Open repository in browser
xdg-open https://github.com/oib/AITBC

# Open specific commit
xdg-open https://github.com/oib/AITBC/commit/$(git rev-parse HEAD)

Best Practices

Commit Messages

• Use conventional commit format: type: description
• Keep messages under 72 characters
• Use imperative mood: "add feature" not "added feature"
• Include body for complex changes

Branch Strategy

• Use main for production-ready code
• Use develop for integration
• Use feature branches for new work
• Keep branches short-lived

Push Frequency

• Push small, frequent commits
• Ensure tests pass before pushing
• Include documentation with code changes
• Tag releases appropriately

Recent Updates (v2.1)

Enhanced Multi-Node Workflow

• Multi-Node Git Status: Check git status on both genesis and follower nodes
• Automatic Sync: Sync follower node with genesis after GitHub push
• Comparison Check: Verify both nodes have the same commit hash
• Sync Verification: Confirm successful synchronization across nodes

Multi-Node Operations

• Status Comparison: Compare git status between nodes
• Hash Verification: Check commit hashes for consistency
• Automatic Sync: Pull changes on follower node after genesis push
• Error Handling: Detect and fix sync issues automatically

Enhanced Troubleshooting

• Multi-Node Sync Issues: Detect and resolve node synchronization problems
• Connectivity Checks: Verify SSH connectivity to follower node
• Sync Validation: Confirm successful node synchronization
• Manual Recovery: Alternative sync methods if automatic sync fails

Quick Commands

• Multi-Node Workflow: Complete workflow with node synchronization
• Quick Sync Check: Fast verification of node status
• Automatic Sync: One-command synchronization across nodes

Previous Updates (v2.0)

Enhanced Workflow

• Comprehensive Operations: Added complete GitHub workflow
• Push Integration: Specific git push to GitHub commands
• Remote Management: GitHub remote configuration
• Troubleshooting: Common issues and solutions

Current Integration

• GitHub Token: Integration with GitHub access token
• Multi-Remote: Support for both Gitea and GitHub
• Branch Management: Complete branch operations
• CI/CD Ready: Integration with automated workflows

Advanced Features

• GitHub CLI: Integration with GitHub CLI tools
• Web Interface: Browser integration
• Best Practices: Documentation standards
• Error Handling: Comprehensive troubleshooting