Add Gitea bot (mimir) configuration for tea-CLI operations

- Add AGENTS.md section 11 documenting mimir bot user for Gitea - Store token via tea logins system with repository:write and user:read scopes - Document common tea commands for branch/PR creation and issue management - Enable agents to create branches, commits and PRs via tea-CLI
2026-04-20 13:24:57 +02:00
parent 231aba08b0
commit 42a5d231b8
5 changed files with 599 additions and 1 deletions
@@ -0,0 +1,170 @@
+# Plan: Gitea Bot User Setup for Tea CLI
+
+## Context
+
+Enable the agent (Kilo) to interact with Gitea (git.phirna.uk) via the `tea` CLI for:
+- Creating branches
+- Committing and pushing changes
+- Creating pull requests
+- Managing issues and labels
+
+## Step 1: Username Suggestion
+
+**Suggested username: `kilo-bot`**
+
+While not directly Norse mythology, "Kilo" evokes the Norse root meaning "coal" or "torch". Alternatives if you prefer pure mythology:
+
+| Username | Origin |
+|----------|--------|
+| `kilo-bot` | Kilo = "torch of life" from Old Norse "Kjöl" |
+| `mimir-bot` | Mimir - Norse god of wisdom, keeper of knowledge |
+| `hnir-bio` | Hnir - "breath" in Old Norse |
+| `sowilo-bot` | Sowilo - the S rune, meaning "sun" |
+
+**Recommendation**: `kilo-bot` — maintains brand consistency with the agent name "Kilo".
+
+## Step 2: Required Permissions
+
+Based on Gitea granular scopes, the bot needs:
+
+| Scope | Reason |
+|-------|--------|
+| `write:repository` | Create branches, push commits, create PRs |
+| `read:repository` | Read branches, commits, repos |
+| `read:user` | Identify authenticated user |
+| `write:issue` | Create/update issues if needed |
+| `read:org` | Read org membership if needed |
+
+**Alternative**: Use `write:repository, read:user` for minimal permissions covering all git operations.
+
+**NOT needed**: `admin` (would allow deleting repos, managing orgs, etc.)
+
+## Step 3: Create the Bot User
+
+Requires admin access on git.phirna.uk. Steps:
+
+1. Go to `https://git.phirna.uk/admin/users/new` (or use `tea admin`)
+2. Create user `kilo-bot` with email (e.g., `kilo-bot@phirna.uk`)
+3. Set a strong random password (store in password manager)
+4. Optionally add to relevant organization(s)
+
+## Step 4: Generate Access Token
+
+1. Login as `kilo-bot`
+2. Go to Settings → Applications → "Manage Access Tokens"
+3. Create token with name `kilo-cli` and scopes:
+   - `repository:write`
+   - `user:read`
+4. Copy the generated token securely
+
+## Step 5: Configure Tea
+
+```bash
+tea logins add --name kilo-bot --url https://git.phirna.uk --token <generated-token>
+```
+
+Or set environment variable `GITEA_TOKEN` or configure in `~/.config/tea/config.yml`.
+
+## Step 6: Update AGENTS.md
+
+Add new section or subsection covering:
+
+- Bot user credentials (token) storage approach
+- Expected token scopes
+- tea command patterns for common operations
+- Security considerations (bot has limited scope)
+
+## Step 7: Create Skill (optional but recommended)
+
+Create `.kilo/.skills/gitea-agent.md`:
+
+- Standardized tea commands for branch creation
+- Commit/push workflow via tea
+- PR creation commands
+- Issue management shortcuts
+
+## Security Considerations
+
+- Bot should **NOT** be admin
+- Token should be scoped to `write:repository` + `read:user` only
+- Token stored in environment or secured config, NOT in repo
+- Consider setting bot's `MaxTokenPermissions` at org level if supported
+
+## Verification Steps
+
+After setup, test:
+
+```bash
+# Verify identity
+tea whoami --login kilo-bot
+
+# List repos (should see assigned repos)
+tea repos list --login kilo-bot
+
+# Create a test branch
+git checkout -b test/tea-cli-test
+git push -u origin test/tea-cli-test --force
+```
+
+## Confirmed Decisions
+
+| Decision | Choice |
+|----------|--------|
+| Username | `mimir` (already created on Gitea) |
+| Token storage | Tea login system (`tea logins add`) |
+| Access scope | All repos on git.phirna.uk |
+
+## Implementation Steps
+
+### Step 1: Generate Access Token for mimir
+
+1. Login to `https://git.phirna.uk` as `mimir`
+2. Go to Settings → Applications → "Manage Access Tokens"
+3. Create token with name `kilo-cli` and scopes:
+   - `repository:write`
+   - `user:read`
+4. Copy the generated token securely
+
+### Step 2: Add Tea Login
+
+```bash
+tea logins add --name mimir --url https://git.phirna.uk --token <generated-token>
+```
+
+Verify with:
+```bash
+tea whoami --login mimir
+```
+
+### Step 3: Update AGENTS.md
+
+Add new section under "Repo-invarianter" or create new section:
+
+```
+## X) Gitea Bot (mimir)
+
+För att kunna skapa branches, commits och PRs via tea:
+
+- Användare: `mimir` på git.phirna.uk
+- Token lagras i tea's login system (`tea logins add`)
+- Scopes: `repository:write`, `user:read`
+- Säkerhet: mimir är inte admin, token har begränsade scopes
+
+Exempel-kommandon:
+tea pr create --login mimir --owner <owner> --repo <repo>
+tea pulls list --login mimir --owner <owner> --repo <repo>
+```
+
+### Step 4: Create Skill (optional)
+
+Create `.kilo/.skills/gitea-agent.md` with tea command patterns.
+
+### Step 5: Verify Access
+
+```bash
+# Should show mimir's identity
+tea whoami --login mimir
+
+# Should list repos mimir can access
+tea repos list --login mimir
+```