ops-jrz1/docs/forgejo-admin.md

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:

# 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

# 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