# 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

```bash
#!/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

```bash
#!/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)

```bash
#!/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:**

```bash
#!/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):

```bash
# .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):

```bash
# 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

```bash
#!/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

```bash
#!/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

```bash
#!/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

```bash
#!/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

```bash
# 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

```bash
# 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](https://docs.gitea.io/en-us/api-usage/)
- [Gitea Access Tokens](https://docs.gitea.io/en-us/api-usage/#token)
- [Gitea Administration](https://docs.gitea.io/en-us/administration/)
- [Issue #156 - Create coordinator bot user](https://git.mosaicstack.dev/mosaic/stack/issues/156)

## Related Issues

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