Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · Interfaces

Token permissions per forge

On this page
  1. GitHub
  2. GitLab
  3. Forgejo and Gitea
  4. Per mode: orchestrator, working directly, answering
  5. When a new version needs more

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:

PermissionWhy
repoRead repositories and issues, send answers as comments, close issues
read:userRecognise which account the token belongs to

Fine-grained token: choose the repositories under "Repository access" and set under "Repository permissions":

PermissionWhy
Metadata: Read-onlyList repositories (GitHub grants this automatically)
Issues: Read and writeRead issues, send answers as comments, close issues

GitLab#

PermissionWhy
apiRead 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".

CategoryAccess levelWhy
userReadRecognise which account the token belongs to
repositoryReadList the repositories of the account
issueRead and writeRead 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.

ForgeWorking directlyOrchestrator, in addition
Forgejo / Gitearepository: Read and write—
GitHub classic——
GitHub fine-grainedContents: Read and writePull requests, Administration, Commit statuses: Read and write
GitLab——
Role in the repositoryWrite (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.

Docs version: dev