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

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