🎯 Quick Reference - GitHub Organization Setup

📋 Checklist

Before You Start

• [ ] Choose your organization name (e.g., recommendai-platform)
• [ ] Have GitHub account ready
• [ ] GitHub CLI installed (gh) OR SSH keys configured

On GitHub.com

• [ ] Create organization at https://github.com/organizations/new
• [ ] Create 7 empty repositories (DO NOT initialize):
  • [ ] recommendai-platform
  • [ ] recommendai-api
  • [ ] recommendai-core
  • [ ] recommendai-ml
  • [ ] recommendai-frontend
  • [ ] recommendai-infrastructure
  • [ ] integration-tests

Local Setup

• [ ] Update .gitmodules with your org name
• [ ] Run .\setup-github-org.ps1 script
• [ ] Initialize parent repo with submodules

🚀 Quick Commands

Option 1: Use the Script (Recommended)

cd "d:\Users\ibadr\Projects\Recommendations"
.\setup-github-org.ps1

Option 2: Manual Setup

# Set your organization name
$ORG = "YOUR_ORG_NAME"

# Push each component
cd recommendai-api
git remote add origin "https://github.com/$ORG/recommendai-api.git"
git push -u origin main

# Repeat for: recommendai-infrastructure, recommendai-core, 
# recommendai-ml, recommendai-frontend, integration-tests

🔑 Authentication

Option A: GitHub CLI (Easiest)

gh auth login
# Follow prompts

Option B: Personal Access Token

1. Go to https://github.com/settings/tokens
2. Generate new token (classic)
3. Select scopes: repo, admin:org
4. Use token as password when pushing

Option C: SSH Keys

1. Generate key: ssh-keygen -t ed25519 -C "your_email@example.com"
2. Add to GitHub: https://github.com/settings/keys
3. Use SSH URLs: git@github.com:ORG/repo.git

📂 Repository URLs Format

https://github.com/YOUR_ORG/recommendai-platform
https://github.com/YOUR_ORG/recommendai-api
https://github.com/YOUR_ORG/recommendai-core
https://github.com/YOUR_ORG/recommendai-ml
https://github.com/YOUR_ORG/recommendai-frontend
https://github.com/YOUR_ORG/recommendai-infrastructure
https://github.com/YOUR_ORG/integration-tests

🎨 Repository Settings (After Creation)

For each repository:

General:

• ✅ Issues enabled
• ✅ Projects enabled
• ✅ Wiki disabled (use docs/ instead)
• ✅ Discussions enabled (optional)

Topics/Tags: All repos: recommendation-system, microservices, b2b-saas

Per repo:

• API: dotnet, csharp, rest-api, graphql
• Core: rust, high-performance
• ML: python, machine-learning, pytorch
• Frontend: angular, typescript
• Infrastructure: docker, kubernetes

Branch Protection (for main):

• ✅ Require pull request reviews (1+)
• ✅ Require status checks to pass
• ✅ Require branches to be up to date
• ✅ Include administrators

👥 Team Structure

Create these teams in your organization:

1. Owners - Full access
2. Backend - Write: api, core, ml
3. Frontend - Write: frontend
4. DevOps - Write: infrastructure
5. QA - Write: integration-tests

🔍 Verification

After setup, verify:

# Clone parent with submodules
git clone --recursive https://github.com/YOUR_ORG/recommendai-platform.git

# Check submodules
cd recommendai-platform
git submodule status

# All should show commit hashes, not errors

📚 Full Documentation

• Complete Guide: GITHUB_ORG_SETUP.md
• Submodules Guide: MONOREPO_SETUP.md
• Ready Status: FINAL_DEPLOYMENT_READY.md

🆘 Troubleshooting

Push Authentication Failed

gh auth login
# Or configure SSH keys

Submodule Issues

git submodule deinit -f .
git submodule update --init --recursive

Wrong Remote URL

cd repository-directory
git remote set-url origin https://github.com/CORRECT_ORG/repo-name.git
git push -u origin main

🎯 Time Estimates

• Create organization: 2 minutes
• Create repositories: 5 minutes
• Push all repos: 5-10 minutes
• Set up submodules: 10 minutes
• Configure settings: 15 minutes

Total: ~30-40 minutes

✅ Success Indicators

You're done when:

1. All 7 repos visible on GitHub
2. Each repo shows correct number of commits
3. Parent repo contains submodules
4. git clone --recursive works
5. All README files display correctly

---

Need help? See detailed guides in documentation files.

Ready? Run .\setup-github-org.ps1 to begin! 🚀