From f17604f0ad58ace933d58462cfd1575d8bbead9f Mon Sep 17 00:00:00 2001
From: Dan <dleink@gmail.com>
Date: Fri, 9 Jan 2026 15:09:09 -0800
Subject: [PATCH] Add Forgejo admin operations doc

---
 docs/forgejo-admin.md | 48 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 docs/forgejo-admin.md

diff --git a/docs/forgejo-admin.md b/docs/forgejo-admin.md
new file mode 100644
index 0000000..5761b48
--- /dev/null
+++ b/docs/forgejo-admin.md
@@ -0,0 +1,48 @@
+# 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