feat(#156): Create coordinator bot user documentation and setup scripts

Add comprehensive documentation and automated scripts for setting up the mosaic coordinator bot user in Gitea. This enables the coordinator system to manage issue assignments, comments, and orchestration. Changes: - docs/1-getting-started/3-configuration/4-gitea-coordinator.md: Complete setup guide * Step-by-step bot user creation via UI and API * Repository permission configuration * API token generation and storage * Comprehensive testing procedures * Security best practices and troubleshooting - scripts/coordinator/create-gitea-bot.sh: Automated bot creation script * Creates mosaic bot user with proper configuration * Sets up repository permissions * Generates API token * Tests authentication * Provides credential output for secure storage - scripts/coordinator/test-gitea-bot.sh: Bot functionality test suite * Tests authentication * Verifies repository access * Tests issue operations (read, list, assign, comment) * Validates label management * Confirms all required permissions - scripts/coordinator/README.md: Scripts usage documentation * Workflow guides * Configuration reference * Troubleshooting section * Token rotation procedures - .env.example: Added Gitea coordinator configuration template * GITEA_URL, GITEA_BOT_USERNAME, GITEA_BOT_TOKEN * GITEA_BOT_PASSWORD, GITEA_REPO_OWNER, GITEA_REPO_NAME * Security notes for credential storage All acceptance criteria met: ✓ Documentation for bot user creation ✓ Automated setup script ✓ Testing procedures and scripts ✓ Configuration templates ✓ Security best practices ✓ Troubleshooting guide Addresses Milestone: M4.1-Coordinator Relates to: #140, #157, #158 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-01 17:32:03 -06:00
parent 32c35d327b
commit de3f3b9204
5 changed files with 1145 additions and 0 deletions
--- a/scripts/coordinator/README.md
+++ b/scripts/coordinator/README.md
@@ -0,0 +1,274 @@
+# Coordinator Scripts
+
+Utility scripts for setting up and managing the autonomous coordinator system in Mosaic Stack.
+
+## Overview
+
+The coordinator system automates issue assignment, tracking, and orchestration across AI agents. These scripts help with setup, configuration, and testing.
+
+## Scripts
+
+### create-gitea-bot.sh
+
+Creates the `mosaic` bot user in Gitea for coordinator automation.
+
+**Prerequisites:**
+
+- Gitea admin access
+- Admin API token with sufficient permissions
+
+**Usage:**
+
+```bash
+# Set admin token and run
+export ADMIN_TOKEN="your-gitea-admin-token"
+./scripts/coordinator/create-gitea-bot.sh
+
+# Or specify variables
+ADMIN_TOKEN="token" GITEA_URL="https://gitea.example.com" \
+  ./scripts/coordinator/create-gitea-bot.sh
+```
+
+**What it does:**
+
+1. Creates `mosaic` bot user account
+2. Sets up email: `mosaic@mosaicstack.dev`
+3. Adds bot to `mosaic/stack` repository as collaborator
+4. Generates API token for coordinator use
+5. Tests bot authentication
+6. Displays credentials for secure storage
+
+**Output:**
+The script provides the API token and password that must be stored in your secrets vault or .env file.
+
+### test-gitea-bot.sh
+
+Tests bot functionality and verifies all necessary permissions.
+
+**Prerequisites:**
+
+- Bot user created (run `create-gitea-bot.sh` first)
+- `GITEA_BOT_TOKEN` in environment or .env file
+
+**Usage:**
+
+```bash
+# Run tests with token from .env
+./scripts/coordinator/test-gitea-bot.sh
+
+# Or specify token explicitly
+export GITEA_BOT_TOKEN="your-bot-token"
+./scripts/coordinator/test-gitea-bot.sh
+
+# Test against specific issue
+export TEST_ISSUE="156"
+./scripts/coordinator/test-gitea-bot.sh
+```
+
+**Tests performed:**
+
+1. Bot authentication
+2. Repository access
+3. Issue listing
+4. Issue reading
+5. Issue assignment
+6. Comment posting
+7. Label management
+8. Repository permissions
+
+**Output:**
+Success/failure for each test with detailed error messages.
+
+## Configuration
+
+### Environment Variables
+
+All scripts support these environment variables:
+
+```bash
+# Gitea connection
+GITEA_URL                # Default: https://git.mosaicstack.dev
+ADMIN_TOKEN              # Gitea admin token (required for create-gitea-bot.sh)
+
+# Bot credentials
+GITEA_BOT_TOKEN          # Bot API token (required for test-gitea-bot.sh)
+GITEA_BOT_USERNAME       # Default: mosaic
+GITEA_BOT_PASSWORD       # For reference only
+
+# Repository
+GITEA_REPO_OWNER         # Default: mosaic
+GITEA_REPO_NAME          # Default: stack
+
+# Testing
+TEST_ISSUE               # Issue number for testing (default: 156)
+```
+
+### .env File
+
+Create or update `.env` file in project root:
+
+```bash
+# Gitea Configuration
+GITEA_URL=https://git.mosaicstack.dev
+GITEA_BOT_USERNAME=mosaic
+GITEA_BOT_TOKEN=your-bot-token-here
+GITEA_BOT_PASSWORD=your-bot-password-here
+GITEA_REPO_OWNER=mosaic
+GITEA_REPO_NAME=stack
+```
+
+**Security:** Never commit .env to version control. Add `.env` to `.gitignore`.
+
+## Workflow
+
+### Initial Setup
+
+```bash
+# 1. Create bot user (requires admin token)
+export ADMIN_TOKEN="your-admin-gitea-token"
+./scripts/coordinator/create-gitea-bot.sh
+
+# Output will show:
+# - Bot username (mosaic)
+# - Bot password (save securely)
+# - API token (save securely)
+# - Instructions for next steps
+
+# 2. Store credentials securely
+# - Add GITEA_BOT_TOKEN to .env (don't commit)
+# - Add GITEA_BOT_TOKEN to your secrets vault
+# - Add GITEA_BOT_PASSWORD to your secrets vault
+
+# 3. Update .env.example (no secrets)
+# - Add template entries with placeholder values
+
+# 4. Test bot functionality
+./scripts/coordinator/test-gitea-bot.sh
+```
+
+### Daily Use
+
+```bash
+# Run tests to verify bot is working
+./scripts/coordinator/test-gitea-bot.sh
+
+# If tests fail:
+# - Check GITEA_BOT_TOKEN is valid
+# - Check token hasn't expired
+# - Verify bot user still exists in Gitea
+# - If needed, regenerate token (see docs)
+```
+
+### Token Rotation
+
+When rotating the bot API token:
+
+```bash
+# 1. Generate new token in Gitea UI
+#    Settings → Applications → Create new token
+
+# 2. Update .env
+export GITEA_BOT_TOKEN="new-token"
+
+# 3. Test new token
+./scripts/coordinator/test-gitea-bot.sh
+
+# 4. Update secrets vault
+# 5. Delete old token in Gitea UI
+```
+
+## Troubleshooting
+
+### "ADMIN_TOKEN environment variable not set"
+
+The `create-gitea-bot.sh` script requires a Gitea admin token.
+
+**Solution:**
+
+1. Log in to Gitea as admin
+2. Go to Settings → Access Tokens
+3. Create new token with `api` scope
+4. Export and run: `ADMIN_TOKEN="token" ./scripts/coordinator/create-gitea-bot.sh`
+
+### "Cannot connect to Gitea"
+
+Script can't reach the Gitea instance.
+
+**Solution:**
+
+```bash
+# Verify GITEA_URL is correct
+echo $GITEA_URL
+
+# Check connectivity
+curl -s https://git.mosaicstack.dev/api/v1/version | jq .
+
+# If still failing, check:
+# - Network connectivity to Gitea server
+# - Firewall rules
+# - VPN/proxy configuration
+```
+
+### "Authentication failed"
+
+Bot API token is invalid or expired.
+
+**Solution:**
+
+1. Check token in .env is correct (no extra spaces)
+2. Verify token hasn't expired (90 day default)
+3. Regenerate token if needed:
+   - Log in as `mosaic` user
+   - Settings → Applications → Delete old token
+   - Create new token
+   - Update .env and secrets vault
+
+### "Bot user already exists"
+
+The bot user was already created.
+
+**Solution:**
+
+- Continue setup with existing user
+- Verify credentials are correct
+- Run tests to confirm functionality
+
+### "Permission denied" on operations
+
+Bot doesn't have required permissions.
+
+**Solution:**
+
+1. Verify bot is added as repository collaborator
+2. Check permission level (should be "push" or "admin")
+3. Re-add if needed via API:
+
+```bash
+curl -X PUT \
+  -H "Authorization: token $ADMIN_TOKEN" \
+  "https://git.mosaicstack.dev/api/v1/repos/mosaic/stack/collaborators/mosaic" \
+  -d '{"permission":"push"}'
+```
+
+## Documentation
+
+For complete documentation on the coordinator bot:
+
+- [Gitea Coordinator Setup Guide](../../docs/1-getting-started/3-configuration/4-gitea-coordinator.md)
+- [Issue #156 - Create coordinator bot user](https://git.mosaicstack.dev/mosaic/stack/issues/156)
+- [Coordinator Architecture](../../docs/3-architecture/non-ai-coordinator-comprehensive.md)
+
+## Related Issues
+
+- #156 - Create coordinator bot user in Gitea
+- #157 - Configure coordinator webhook in Gitea
+- #158 - Implement coordinator task assignment engine
+- #140 - Coordinator integration architecture
+
+## Support
+
+For issues or questions:
+
+1. Check the troubleshooting section above
+2. Review the full documentation
+3. Open an issue in the repository