mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Jason Woltje
2026-02-01 17:32:03 -06:00
parent 32c35d327b
commit de3f3b9204
5 changed files with 1145 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

378
docs/1-getting-started/3-configuration/4-gitea-coordinator.md Normal file
View File

@@ -0,0 +1,378 @@
# 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