zima-apps/.kilo/plans/1776672399841-quick-meadow.md

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

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:

# 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

tea logins add --name mimir --url https://git.phirna.uk --token <generated-token>

Verify with:

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

# Should show mimir's identity
tea whoami --login mimir

# Should list repos mimir can access
tea repos list --login mimir