For developers · Interfaces
Token permissions per forge
On this page
Gitoodo needs a personal access token per account. The token wizard (Settings > account > add or
renew) names the permissions in the words of the forge's own token page, with the reason for each.
This page is the same list for later. The wizard texts live in src/views/settings/permissionGuide.ts;
tests/token-permissions.test.ts fails when this page, the wizard and the checks in
crates/core/src/forge drift apart.
GitHub#
Classic token (Settings > Developer settings > Personal access tokens (classic)); the wizard opens the page with both boxes ticked:
| Permission | Why |
|---|---|
repo | Read repositories and issues, send answers as comments, close issues |
read:user | Recognise which account the token belongs to |
Fine-grained token: choose the repositories under "Repository access" and set under "Repository permissions":
| Permission | Why |
|---|---|
| Metadata: Read-only | List repositories (GitHub grants this automatically) |
| Issues: Read and write | Read issues, send answers as comments, close issues |
GitLab#
| Permission | Why |
|---|---|
api | Read issues, send answers as comments, close issues |
read_api is enough for reading only; without api Gitoodo cannot answer.
Forgejo and Gitea#
Forgejo and Gitea cannot preselect permissions by link. Set them by hand on the opened page (User settings > Applications): pick this access level for each category and leave all others on "No access".
| Category | Access level | Why |
|---|---|---|
user | Read | Recognise which account the token belongs to |
repository | Read | List the repositories of the account |
issue | Read and write | Read issues, send answers as comments, close issues |
Per mode: orchestrator, working directly, answering#
The lists above are what answering questions needs. The wizard asks what Gitoodo should do with the
repositories, preselects the operating mode chosen in onboarding (or set in the app) and shows one
merged list for that mode: each category once, the highest access level wins, plus the role the
account needs in the repository. It goes on only after I have set these permissions on the token
is ticked; switching to a mode that needs more asks again. The rights per mode come from
crates/core/src/forge/rights.rs, the merge from src/views/settings/tokenBlock.ts.
| Forge | Working directly | Orchestrator, in addition |
|---|---|---|
| Forgejo / Gitea | repository: Read and write | — |
| GitHub classic | — | — |
| GitHub fine-grained | Contents: Read and write | Pull requests, Administration, Commit statuses: Read and write |
| GitLab | — | — |
| Role in the repository | Write (GitLab: Developer) | Admin (GitLab: Maintainer), for repository settings such as merge styles and branch protection |
A separate orchestrator (worker) account per forge host (#764, docs/orchestrator/spec.md 5.3.1)
needs the orchestrator's rights without repository settings (forge::rights::worker_rights): no
Administration permission and no admin role; write access (GitLab: Developer, Maintainer to merge
into protected branches) is enough. Repository settings stay with the user's own account.
When a new version needs more#
The check runs when an account is added, renewed and synced. If the stored token lacks a permission, the account shows what is missing and offers Renew token; the wizard then marks the missing permissions in the list. Create a new token on the forge with all permissions named above, paste it in the wizard; the old token is replaced in place and the account keeps its settings.
Release rule: a version that adds a required permission lists it in the changelog under "Added" or "Changed" as "New permission required: ...", and the permission appears in the lists above.