stack/docs/1-getting-started/3-configuration/4-gitea-coordinator.md

Gitea Coordinator Bot Setup

Milestone: M4.1-Coordinator Issue: #156 - Create coordinator bot user in Gitea

This document describes how to set up the mosaic bot user in Gitea for automated coordinator functionality.

Overview

The coordinator bot is a Gitea user account used by the autonomous coordination system to:

• Assign issues to agent workers
• Comment on issues with task assignments
• Update issue labels and milestones
• Close issues after completion
• Provide audit trail of coordinator actions

Bot Account Details:

• Username: mosaic
• Email: mosaic@mosaicstack.dev
• Type: Bot account
• Repository: mosaic/stack

Prerequisites

• Gitea instance running at https://git.mosaicstack.dev
• Admin access to Gitea
• API access capability

Step 1: Create the Bot User

Via Gitea Web UI

1. Access Gitea Admin Panel

   • Navigate to https://git.mosaicstack.dev/admin
   • Log in with your admin account

2. Create New User

   • Go to User Accounts → Create New User
   • Fill in the following fields:

   Field	Value
   Username	mosaic
   Email	mosaic@mosaicstack.dev
   Password	[Generate random secure password]
   Send Activation Email	✅ (checked)
   Account Type	Account Type: Organization (bot-like behavior)
   Admin	☐ (unchecked)
   Restricted Account	☐ (unchecked)
   Disable 2FA	✅ (checked)

3. Review and Create

   • Click Create User Account
   • Note the generated temporary password if provided

Via API

#!/bin/bash
# Set variables
GITEA_URL="https://git.mosaicstack.dev"
ADMIN_TOKEN="your-admin-token-here"
BOT_USERNAME="mosaic"
BOT_EMAIL="mosaic@mosaicstack.dev"
BOT_PASSWORD="$(openssl rand -base64 32)"

# Create user
curl -s -X POST \
  -H "Authorization: token $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  "$GITEA_URL/api/v1/admin/users" \
  -d "{
    \"username\": \"$BOT_USERNAME\",
    \"email\": \"$BOT_EMAIL\",
    \"password\": \"$BOT_PASSWORD\",
    \"must_change_password\": false,
    \"send_notify\": false
  }"

# Store password securely (see Step 3)
echo "Bot user created with temporary password: $BOT_PASSWORD"

Step 2: Configure Repository Permissions

The bot user needs read and write access to the mosaic/stack repository.

Add Bot as Collaborator

1. Navigate to Repository

   • Go to https://git.mosaicstack.dev/mosaic/stack
   • Go to Settings → Collaborators

2. Add Bot User

   • Search for mosaic
   • Select Push permission (allows pull + push)
   • Or use Admin if full repository control needed

Via API

#!/bin/bash
GITEA_URL="https://git.mosaicstack.dev"
REPO_OWNER="mosaic"
REPO_NAME="stack"
BOT_USERNAME="mosaic"
ADMIN_TOKEN="your-admin-token-here"

# Add collaborator
curl -s -X PUT \
  -H "Authorization: token $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/collaborators/$BOT_USERNAME" \
  -d '{"permission":"push"}'

echo "Bot added as collaborator with push permission"

Step 3: Generate and Store API Token

The coordinator needs an API token to authenticate Gitea API calls.

Generate Token

1. Login as Bot User

   • Log in to Gitea with username mosaic
   • Complete any initial setup (verify email, set password, etc.)

2. Create Access Token

   • Go to Settings → Applications → Access Tokens
   • Create token with these settings:

   Setting	Value
   Token Name	coordinator-api-token
   Scopes	api, read:repository, write:repository, write:issue
   Expiration	90 days (recommended for security)

3. Copy and Store Token

   • Copy the token immediately (it won't be shown again)
   • Store securely in your secrets management system

Via API (as Admin)

#!/bin/bash
GITEA_URL="https://git.mosaicstack.dev"
ADMIN_TOKEN="your-admin-token-here"
BOT_USERNAME="mosaic"

# Create access token for bot user
curl -s -X POST \
  -H "Authorization: token $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  "$GITEA_URL/api/v1/admin/users/$BOT_USERNAME/tokens" \
  -d '{
    "name": "coordinator-api-token",
    "scopes": ["api", "read:repository", "write:repository", "write:issue"]
  }' | jq -r '.sha1'

Step 4: Store Credentials in Vault

For production environments using Vault:

Store the bot credentials in your Vault instance at:

secret-prod/gitea/coordinator/api-token
secret-prod/gitea/coordinator/password

Example Vault setup:

#!/bin/bash
VAULT_ADDR="https://vault.example.com"
VAULT_TOKEN="your-vault-token"

# Store API token
curl -X POST \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  "$VAULT_ADDR/v1/secret/data/gitea/coordinator/api-token" \
  -d '{"data":{"token":"your-api-token-here"}}'

# Store password (for recovery/rotation)
curl -X POST \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  "$VAULT_ADDR/v1/secret/data/gitea/coordinator/password" \
  -d '{"data":{"password":"bot-password-here"}}'

For development (non-production):

Store in .env file (never commit):

# .env (NEVER COMMIT)
GITEA_BOT_TOKEN=your-api-token-here
GITEA_BOT_USERNAME=mosaic
GITEA_BOT_PASSWORD=your-bot-password-here
GITEA_URL=https://git.mosaicstack.dev

Add to .env.example (with placeholders):

# Gitea Coordinator Bot Configuration
GITEA_URL=https://git.mosaicstack.dev
GITEA_BOT_USERNAME=mosaic
GITEA_BOT_TOKEN=your-coordinator-bot-token-here
GITEA_BOT_PASSWORD=your-coordinator-bot-password-here

Step 5: Test Bot Functionality

Test 1: API Authentication

#!/bin/bash
GITEA_URL="https://git.mosaicstack.dev"
BOT_TOKEN="your-bot-token"

# Verify token works
curl -s -H "Authorization: token $BOT_TOKEN" \
  "$GITEA_URL/api/v1/user" | jq .

# Expected output:
# {
#   "id": <user-id>,
#   "username": "mosaic",
#   "email": "mosaic@mosaicstack.dev",
#   ...
# }

Test 2: Assign Issue to Bot

#!/bin/bash
GITEA_URL="https://git.mosaicstack.dev"
REPO_OWNER="mosaic"
REPO_NAME="stack"
ISSUE_NUMBER="156"
BOT_TOKEN="your-bot-token"

# Assign issue to bot user
curl -s -X PATCH \
  -H "Authorization: token $BOT_TOKEN" \
  -H "Content-Type: application/json" \
  "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/issues/$ISSUE_NUMBER" \
  -d '{"assignees":["mosaic"]}' | jq .

# Check assignment succeeded
curl -s -H "Authorization: token $BOT_TOKEN" \
  "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/issues/$ISSUE_NUMBER" | \
  jq '.assignees[] | .username'

# Expected output: mosaic

Test 3: Comment as Bot

#!/bin/bash
GITEA_URL="https://git.mosaicstack.dev"
REPO_OWNER="mosaic"
REPO_NAME="stack"
ISSUE_NUMBER="156"
BOT_TOKEN="your-bot-token"

# Post comment as bot
curl -s -X POST \
  -H "Authorization: token $BOT_TOKEN" \
  -H "Content-Type: application/json" \
  "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/issues/$ISSUE_NUMBER/comments" \
  -d '{"body":"Test comment from coordinator bot"}' | jq .

# Expected: Comment created successfully with bot as author

Test 4: Update Labels

#!/bin/bash
GITEA_URL="https://git.mosaicstack.dev"
REPO_OWNER="mosaic"
REPO_NAME="stack"
ISSUE_NUMBER="156"
BOT_TOKEN="your-bot-token"

# Add label via bot
curl -s -X PATCH \
  -H "Authorization: token $BOT_TOKEN" \
  -H "Content-Type: application/json" \
  "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/issues/$ISSUE_NUMBER" \
  -d '{"labels":["coordinator","in-progress"]}' | jq .

# Expected: Labels updated successfully

Coordinator Bot Permissions Summary

Action	Required Permission	Verified
List issues	read:repository	✅
Read issue details	read:repository	✅
Assign issue	write:issue	✅
Comment on issue	write:issue	✅
Update labels	write:repository	✅
Close/reopen issue	write:issue	✅
Read pull requests	read:repository	✅
Comment on PR	write:issue	✅

Troubleshooting

Bot User Won't Authenticate

# Verify token is valid and not expired
curl -s -H "Authorization: token $GITEA_BOT_TOKEN" \
  "https://git.mosaicstack.dev/api/v1/user" | jq .

# If 401 Unauthorized: Token is invalid or expired
# - Check token spelling/format
# - Verify token hasn't expired
# - Regenerate token if needed

Permission Denied on Issues

# Verify bot has repository access
curl -s -H "Authorization: token $GITEA_BOT_TOKEN" \
  "https://git.mosaicstack.dev/api/v1/repos/mosaic/stack" | jq .

# If 403 Forbidden:
# - Add bot as collaborator with push permissions
# - Check repository settings allow bot access

Token Rotation

To rotate the API token:

1. Generate new token (see Step 3)
2. Update configuration with new token
3. Test with new token
4. Delete old token in Gitea settings
5. Verify all integrations working with new token

Security Best Practices

1. Token Rotation — Rotate tokens every 90 days
2. Scoped Permissions — Use minimum required scopes (api, write:issue)
3. Restricted Account — Mark as restricted if Gitea version supports it
4. Audit Logging — Monitor bot activity via Gitea audit logs
5. Disable 2FA — Disable 2FA for bot accounts (only use API tokens)
6. Secure Storage — Never commit credentials to version control
7. Service Account — Treat as privileged service account
8. Regenerate on Compromise — Immediately regenerate token if compromised

Additional Resources

• Gitea API Documentation
• Gitea Access Tokens
• Gitea Administration
• Issue #156 - Create coordinator bot user

Related Issues

• #140 - Coordinator integration architecture
• #157 - Coordinator webhook configuration
• #158 - Coordinator task assignment engine