# Forgejo Administration

Admin operations for git.clarun.xyz (Forgejo on ops-jrz1).

## API Token Generation

The dev-provisioning token at `/run/secrets/forgejo-api-token` has admin user scope only. For repo operations, generate a temporary scoped token:

```bash
# Find the correct gitea binary (must match deployed Forgejo version)
# Check version with: systemctl status forgejo
GITEA_BIN=$(find /nix/store -name "gitea" -path "*forgejo-7*" -type f -executable | head -1)

# Generate scoped token
ssh root@ops-jrz1 "sudo -u forgejo $GITEA_BIN admin user generate-access-token \\
  --username dan \\
  --token-name 'temp-task-name' \\
  --scopes 'write:repository,read:repository' \\
  --config /var/lib/forgejo/custom/conf/app.ini"
```

**Common scopes:**
- `write:admin,read:admin,write:user` - User provisioning (dev-add.sh)
- `write:repository,read:repository` - Repo settings

## Repo Settings via API

```bash
# Update default branch
ssh root@ops-jrz1 'curl -s -X PATCH "http://localhost:3000/api/v1/repos/OWNER/REPO" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"default_branch\": \"main\"}"'

# After fix, update local git
git remote set-head origin main
git fetch origin
```

## Cleanup

Delete temporary tokens at: https://git.clarun.xyz/user/settings/applications

## Gotchas

- **Binary version mismatch**: Newer gitea binaries fail with DB column errors. Use the version matching your deployed Forgejo.
- **Token scopes**: API returns 403 if token lacks required scope - error message shows which scope is needed.
- **API docs**: https://git.clarun.xyz/api/swagger