stack/scripts/coordinator/README.md

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:

# 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:

# 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:

# 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:

# 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

# 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

# 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:

# 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:

# 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:

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
• Issue #156 - Create coordinator bot user
• Coordinator Architecture

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