Skip to content

MULTI_PLATFORM_SETUP.md

Latest commit

 

History

History
501 lines (383 loc) · 12.2 KB

MULTI_PLATFORM_SETUP.md

File metadata and controls

501 lines (383 loc) · 12.2 KB

Multi-Platform Publication Setup

Purpose: Cross-publish Behaviour Lab on both GitHub and GitLab with automated sync Strategy: Common upstream with CI/CD handling platform differences Primary Platform: [Choose: GitHub or GitLab]

🎯 Architecture Overview

┌─────────────────┐
│  Your Local Repo│
│  (Upstream)     │
└────────┬────────┘
         │
    git push
         │
    ┌────▼─────┐
    │  GitHub  │◄──── Primary (recommended)
    │  Actions │
    └────┬─────┘
         │ Auto-sync
         │
    ┌────▼─────┐
    │  GitLab  │◄──── Mirror
    │    CI    │
    └──────────┘

Benefits:

  • ✅ Broader reach (both platforms)
  • ✅ Platform redundancy
  • ✅ Different communities (GitHub: dev/AI, GitLab: enterprise/privacy-focused)
  • ✅ Automatic sync (no manual work)
  • ✅ Platform-specific features on each

📋 Setup Instructions

Step 1: Choose Primary Platform

Recommendation: GitHub as Primary

  • Larger developer community
  • Better for open source discovery
  • More familiar to most users
  • GitLab syncs FROM GitHub automatically

Alternative: GitLab as Primary

  • Privacy-focused community
  • Better CI/CD features
  • Self-hosting possible
  • GitHub syncs FROM GitLab

For this guide, we'll use GitHub as primary.

Step 2: Create Repositories

A. GitHub Repository (Primary)

# Create on GitHub.com
# Repository: behaviour-lab
# Visibility: Public
# Description: "Programmable Human Behaviour Through Evidence-Based Agent Coordination"

# Then push from local:
cd ~/Documents/GitHub/behaviour-lab

git init
git add .
git commit -m "Initial release: Stage 1 with ethical framework"
git branch -M main
git remote add origin https://github.com/[username]/behaviour-lab.git
git push -u origin main

B. GitLab Repository (Mirror)

Option 1: GitLab.com (Recommended)

# Create on GitLab.com
# Project name: behaviour-lab
# Visibility: Public
# Description: Mirror of GitHub repository with ethical framework

# Add as second remote:
cd ~/Documents/GitHub/behaviour-lab
git remote add gitlab https://gitlab.com/[username]/behaviour-lab.git
git push gitlab main

Option 2: Self-Hosted GitLab

# Use your own GitLab instance
git remote add gitlab https://your-gitlab.example.com/[username]/behaviour-lab.git
git push gitlab main

Step 3: Set Up GitHub Actions (Auto-Sync)

Already created: .github/workflows/sync-to-gitlab.yml

Configure Secrets:

  1. Create GitLab Personal Access Token:

    • GitLab → Settings → Access Tokens
    • Name: "GitHub Actions Sync"
    • Scopes: api, write_repository
    • Copy token

  2. Add to GitHub Secrets:

    • GitHub Repo → Settings → Secrets and variables → Actions
    • New repository secret:
      • Name: GITLAB_TOKEN
      • Value: [paste token]
    • Add another secret:
      • Name: GITLAB_REPO
      • Value: [username]/behaviour-lab
    • Optional:
      • Name: GITLAB_URL
      • Value: https://gitlab.com (or your instance)

Test Sync:

# Make a small change
echo "\n\n---\n**Last sync:** $(date)" >> README.md
git add README.md
git commit -m "Test sync to GitLab"
git push origin main

# Check GitHub Actions tab - should see sync running
# Check GitLab repo - should update within 1-2 minutes

Step 4: Set Up GitLab CI (Validation)

Already created: .gitlab-ci.yml

What it does:

  • ✅ Validates ethical warnings present
  • ✅ Checks LICENSE.md correctness
  • ✅ Scans for secrets
  • ✅ Tests Python code
  • ✅ Optional: Deploys GitLab Pages

Activate:

# Push .gitlab-ci.yml if not already
git add .gitlab-ci.yml
git commit -m "Add GitLab CI for validation"
git push origin main  # Will auto-sync to GitLab

# GitLab will automatically detect and run pipeline

Step 5: Configure Platform-Specific Features

GitHub-Specific:

Enable Features:

  • Settings → Features → Discussions: ✅ Enable
  • Settings → Features → Issues: ❌ Disable initially
  • Settings → Features → Projects: ✅ Enable
  • Settings → Features → Wiki: ❌ Disable

Add Topics:

  • behavior-engineering, priming, nudging, ethics, ai-ethics, human-ai-interaction

Create Labels:

  • ethics-concern (red)
  • misuse-report (critical, red)
  • research-question (blue)
  • enhancement (green)

GitLab-Specific:

Enable Features:

  • Settings → General → Visibility → Issues: ❌ Disable
  • Settings → General → Visibility → Merge Requests: ✅ Enable
  • Settings → General → Visibility → Wiki: ❌ Disable
  • Settings → Repository → Push Rules: Configure

Add Topics: Same as GitHub, plus:

  • gitlab-mirror
  • synced-from-github

Set Up Mirror (Alternative Method):

  • Settings → Repository → Mirroring repositories
  • Git repository URL: https://github.com/[username]/behaviour-lab.git
  • Mirror direction: Pull
  • Authentication: [GitHub token]

Step 6: Platform-Specific README Badges

Add to README.md (top, after title):

[![GitHub](https://img.shields.io/badge/GitHub-Primary-blue?logo=github)](https://github.com/[username]/behaviour-lab)
[![GitLab](https://img.shields.io/badge/GitLab-Mirror-orange?logo=gitlab)](https://gitlab.com/[username]/behaviour-lab)
[![License](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0%20%2B%20Ethics-green)](LICENSE.md)
[![Stage](https://img.shields.io/badge/Publication-Stage%201-blue)](PUBLICATION-PLAN.md)

> **Multi-Platform:** This project is published on both GitHub (primary) and GitLab (mirror) to reach broader communities while maintaining ethical standards.

Step 7: Configure Sync Behavior

Choose Sync Strategy:

Option A: Unidirectional (GitHub → GitLab)

  • GitHub is source of truth
  • GitLab automatically mirrors
  • Simpler, less conflict risk
  • Recommended for start

Option B: Bidirectional (Advanced)

  • Both platforms can be updated
  • Requires conflict resolution
  • More complex CI/CD
  • Use if different communities contribute on each

For Option A (Recommended):

  • GitHub Actions syncs TO GitLab: ✅ (already set up)
  • GitLab issues/MRs redirect to GitHub
  • Add note to GitLab README: 
    ## Contributing

This is a mirror from GitHub. Please contribute on GitHub:
https://github.com/[username]/behaviour-lab

For Option B (Advanced): See BIDIRECTIONAL_SYNC_ADVANCED.md (create if needed)

Step 8: Test Complete Setup

Checklist:

  1. Push to GitHub:

    cd ~/Documents/GitHub/behaviour-lab
echo "\n## Test Update $(date)" >> test.md
git add test.md
git commit -m "Test multi-platform sync"
git push origin main

  2. Verify GitHub Actions:

    • GitHub → Actions tab
    • Should see "Sync to GitLab" running
    • Should complete successfully (green checkmark)

  3. Verify GitLab Sync:

    • Visit GitLab repo
    • Refresh after 1-2 minutes
    • Should see test.md with update

  4. Verify GitLab CI:

    • GitLab → CI/CD → Pipelines
    • Should see pipeline running
    • All checks should pass (green)

  5. Clean up test:

    git rm test.md
git commit -m "Remove test file"
git push origin main

🎯 Daily Workflow

As Maintainer:

  1. Make changes locally:

    cd ~/Documents/GitHub/behaviour-lab
# Edit files
git add .
git commit -m "Your changes"

  2. Push to GitHub (primary):

    git push origin main

  3. Automatic sync happens:

    • GitHub Actions pushes to GitLab
    • GitLab CI validates changes
    • Both platforms updated within minutes

  4. Monitor both platforms:

    • Check GitHub Discussions/PRs
    • Check GitLab Issues/MRs (if enabled)
    • Respond to feedback on both

🛡️ Platform-Specific Safety Features

GitHub:

  • Discussions for community feedback
  • Dependabot for security alerts
  • Code scanning for security issues
  • Secret scanning automatic

GitLab:

  • CI/CD pipelines for validation
  • Push rules to enforce standards
  • Approval rules for merges
  • Security dashboard

Both platforms working together = stronger safety!

📊 Monitoring Both Platforms

Daily Checks:

  • GitHub: Check Discussions, PRs, Actions status
  • GitLab: Check Issues, MRs, Pipeline status
  • Both: Search for external mentions
  • Both: Review new forks for ethical compliance

Weekly Review:

## Week of [Date]

**GitHub:**
- Stars: [X] (+Y this week)
- Forks: [X] (+Y this week)
- Discussions: [X] active threads
- Actions: [X] successful / [Y] failed

**GitLab:**
- Stars: [X] (+Y this week)
- Forks: [X] (+Y this week)
- Issues: [X] open / [Y] closed
- Pipelines: [X] passed / [Y] failed

**Combined Reach:** [X+Y] total stars
**Misuse Reports:** [Hopefully 0]
**Action Items:** [List any concerns]

🔧 Troubleshooting

Sync Failed (GitHub → GitLab)

Check:

  1. GitLab token still valid?
  2. GitLab repo exists and accessible?
  3. No force push conflicts?

Fix:

# Manual sync if automated fails
git remote update
git push gitlab main --force  # Use with caution
git push gitlab --tags --force

CI Pipeline Failed on GitLab

Common causes:

  1. Missing ethical warnings (intentional check)
  2. LICENSE.md modified incorrectly
  3. Secrets detected
  4. Python code has errors

Fix based on error message in GitLab pipeline logs

Both Platforms Out of Sync

Nuclear option (reset both to local):

cd ~/Documents/GitHub/behaviour-lab
git push origin main --force
git push gitlab main --force

🎯 Launch on Both Platforms

Use LAUNCH_CHECKLIST.md but for BOTH:

  1. Create both repositories (GitHub, then GitLab)
  2. Configure sync (GitHub Actions + GitLab CI)
  3. Test sync (make sure it works)
  4. Push initial release to GitHub (will auto-sync)
  5. Create release tags on both: 
    git tag -a v1.0.0-stage1 -m "Stage 1 Release"
git push origin v1.0.0-stage1
git push gitlab v1.0.0-stage1
  6. Announce on both platforms
  7. Monitor both for feedback

📞 Quick Commands

Add both remotes:

cd ~/Documents/GitHub/behaviour-lab
git remote add origin https://github.com/[username]/behaviour-lab.git
git remote add gitlab https://gitlab.com/[username]/behaviour-lab.git

Push to both:

git push origin main
git push gitlab main

Or use --all (push to all remotes):

git remote add all https://github.com/[username]/behaviour-lab.git
git remote set-url --add --push all https://github.com/[username]/behaviour-lab.git
git remote set-url --add --push all https://gitlab.com/[username]/behaviour-lab.git
git push all main

Check sync status:

git remote -v
git log --oneline --graph --all

✅ Multi-Platform Setup Complete Checklist

  • GitHub repository created (primary)
  • GitLab repository created (mirror)
  • Both remotes added to local repo
  • GitHub Actions sync configured (.github/workflows/sync-to-gitlab.yml)
  • GitLab CI validation configured (.gitlab-ci.yml)
  • GitHub secrets added (GITLAB_TOKEN, GITLAB_REPO)
  • Sync tested and working
  • CI pipeline tested and passing
  • Platform-specific features configured
  • README badges added
  • Monitoring setup for both platforms
  • Ready to launch on both! 🚀

🎉 Benefits of Multi-Platform

Broader Reach:

  • GitHub: 100M+ developers, AI/ML community strong
  • GitLab: Privacy-focused, enterprise, EU strong

Redundancy:

  • If one platform has issues, other is still available
  • Community isn't locked to single platform

Different Communities:

  • GitHub: Open source, AI ethics, research
  • GitLab: DevOps, security, self-hosting advocates

Better Safety:

  • Two CI systems validating everything
  • Two communities watching for misuse
  • Double the monitoring

Professional:

  • Shows thoughtfulness and inclusivity
  • Respects platform preferences
  • Demonstrates technical capability

You're ready for multi-platform launch! 🚀

Next: Follow LAUNCH_CHECKLIST.md but for BOTH platforms simultaneously.