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

For developers · Orchestrator

Orchestrator setup

On this page
  1. 0. Install
  2. 1. Background service
  3. 2. Account and token
  4. 3. Map labels
  5. 4. Activate a repository
  6. 5. Local copy
  7. 6. Skill and agent instructions
  8. 7. First worker
  9. Final check
  10. What the assistant never does

The app guides you through the orchestrator setup and does each step for you. On first start the onboarding offers orchestrator mode (preselected) next to the plain to-do list. With orchestrator mode, the onboarding sets up every repository picked in its repo step in one go, right after that step: you choose once what happens to issues that are already open and press Set up now. Gitoodo then installs the background service (the signed release reads tokens through the service helper without any keychain step; other builds grant the services access once, macOS may ask: choose Always Allow), renames legacy labels and creates missing ones, switches each repo on, clones missing local copies into the clone folder, installs the skill for the worker agent and starts the dispatcher. Each part and each repository shows its own state; Try again repeats only what failed. Own label names, single repositories and agent instructions stay in the settings.

The assistant below covers the same steps one by one, for a skipped onboarding step, later changes and single repositories. Open it from Settings → Setup assistant, or from Settings → Mode once orchestrator mode is selected.

The assistant stores no progress of its own. Each time it opens, and whenever you press Check again, it checks the real state of the service, the accounts, the labels, the repository state and the dispatcher. It then continues at the first step that is still open. You can stop at any point and resume later, or run it again on a finished setup: steps that are already done stay done and are skipped.

The assistant opens in its own window, shows one step per page with Back and Next and a progress bar of all steps, and moves on by itself once a step is done (#589).

Everything the assistant does is also possible by hand. Each step below names the manual way.

0. Install#

Install the app from the download on the landing page (macOS DMG, Windows setup). On macOS, curl -fsSL https://gitoodo.com/install.sh | bash installs the app and the gitoodo command; on Windows, irm https://gitoodo.com/install.ps1 | iex does the same. Then open Settings → Setup assistant. The matching uninstall.sh / uninstall.ps1 removes the services and everything else again (see the README).

1. Background service#

Check: the classifier answers on its local socket and reports its version, its secret backend and whether its first poll has finished. Accounts the last poll could not read are shown as a hint.

Assistant: registers the classifier with the system service manager and waits until it answers. This is launchd on macOS, a systemd user unit on Linux and a scheduled task on Windows. When the service is registered but silent, Set up service again restarts it. If the gitoodo command line program is missing (it is looked for next to the app, then on PATH), the step says so.

The assistant first copies the bundled CLI to a per-user folder and the services run that copy, so moving or updating the app does not break them; both services restart on their own after a crash or a reboot. The step shows the app and installed CLI versions; when they differ from each other or from the running classifier, Reinstall aligns them. Classifier and dispatcher each have Start, Stop and Remove. The store builds install no services.

By hand: gitoodo service install|uninstall|start|stop [classifier|dispatcher|all], gitoodo --version. On a system without a service manager, run gitoodo classifier in a terminal. gitoodo doctor checks the result.

2. Account and token#

Check: at least one account is connected and no account's token lacks a permission or has expired.

Assistant: opens the account wizard. To renew a token it opens the same wizard for that account. Tokens go to the system keychain only.

By hand: Settings → Accounts.

Orchestrator account (#764): per forge host the orchestrator acts as a chosen account. The onboarding step "Worker-Konto" recommends a separate bot account and guides through it per forge: create the account, give it write access to the repos (Forgejo/Gitea: collaborator with write or a team; GitHub: collaborator or team with Write; GitLab: Developer, Maintainer for protected branches), sign in as the bot and create a token with the rights listed there (the orchestrator's rights without repository settings), and allow it to merge under branch protection. The token goes through the normal account wizard, so it lands in the system keychain only. The check then shows the bot's login, missing scopes and every activated repo it cannot work in, with a link to grant access. Using the own account stays possible; the history then shows the user's name. Change and check it later under Settings → Accounts → Orchestrator-Konto.

3. Map labels#

Check: the target repository has every catalog label (see spec.md, section 5.1) and no legacy label names the migration would rename (#591). The target is the first active repository of a connected account; if there is none, you pick an account and a repository.

Assistant: shows the labels the repository lacks. For each one you can use a label the repository already has, or have it created. The mapping applies to all repositories and is written to profile.names in Gitoodo's own orchestration.json. Missing labels are created only after you confirm the list. Legacy labels (for example prio:1, status:*) are listed as old → new and renamed by the same click (the #567 migration), so no English duplicates appear beside them; issues and pull requests keep their labels. Labels already in use under their catalog name are listed as "stay as they are". Where a legacy name and its catalog name both exist, both stay and are named as a pair; Gitoodo merges nothing, and the step does not wait on such a pair. Other existing labels are never changed or deleted.

The onboarding's setup step and Adopt several repositories … show the same preview for every picked repository before anything is written: a total line (kept, renamed, new) and per repository the labels it keeps, renames (old → new) and gets created. It is read from the forge without writing; a repository whose labels cannot be read says so and can be read again.

By hand: set profile.names in <config>/orchestration.json (catalog name to your label name, see daemon.md) and create the labels on the forge. The classifier also recreates missing catalog labels in active repositories on its next run.

4. Activate a repository#

Check: the target repository is listed in orchestration.json with the state active and is not switched off in the settings.

Assistant: sets the repository to active. This means the orchestrator may take issues labelled ready (or your mapped name) and set labels in that repository. Before a repository writes for the first time, the assistant (and Settings → Repositories) shows a preview read from the forge without writing: how many issues are open, how many would become ready, how many would get an approval or clarification question and to whom, how many labels and milestones would be set (#598). You pick what happens to the issues that are already open:

  • Only handle new issues (default): issues and pull requests opened before this moment get no labels, comments or milestones.
  • Take existing issues as ready: they become ready without a question.
  • Check existing issues and ask: the normal intake; questions go out at most five per repository and run, the rest is logged as "N more questions pending".

Questions mention the configured person of the repository, else the connected account, never the owning organisation. The choice is stored as backlog (new, ready, ask) with adopted_at in the repository's rule; rules written before #598 behave like ask. If no suitable repository exists yet, Create a new project or Adopt an existing repository open the project wizard inside the assistant.

Adopt several repositories … (#590) lists the account's other repositories with a search field and "All of <owner>" per owner or organisation, plus its own choice for open issues (default: only new issues). Nothing is written until Adopt N repositories; until then any repository can be deselected, and the label preview above the button lists what each selected repository keeps, renames and gets created. The onboarding's repo step offers the same "All of <owner>" switch when an account reaches repositories of several owners or organisations. The repositories are then handled one after the other, each with its status (waiting, setting up, turned on, failed): legacy labels are renamed and missing ones created, then the repository is switched on. A failed repository does not stop the others; retry it under Settings → Repositories. The local-copy step then lists every adopted repository.

By hand: Settings → Repositories, or add the repository with "state": "active" to repos in orchestration.json.

5. Local copy#

Check: the dispatcher has a local copy of the target repository.

Each worker works in its own worktree of this copy: it creates a branch there, opens a pull request and merges it into the base branch.

The dispatcher uses, in this order: the folder set for the repository, a clone found by its origin in the projects folders or the clone folder (any layout), else <dispatch.clone_root>/<owner>/<repository> (#592; default clone folder ~/gitoodo/repos, a folder of Gitoodo's own, #735). In a copy of yours Gitoodo only fetches and creates its <prefix>/… branches and worktrees (under dispatch.worktree_root); it never checks out, resets or cleans your working tree. The worktree folder must lie apart from the clone and projects folders. The step shows the clone folder with Change…, which opens the native folder picker (Finder, Explorer, the desktop portal) and applies to every repository. The assistant lists the clone of every active repository:

  • No clone yet (nothing there or an empty folder): "Clone" clones it with the connected account. The token reaches only that one git clone through GIT_ASKPASS, as with gitoodo worker push; origin is the plain HTTPS URL and no token lands in .git/config, a file, a log or an error text.
  • Clone present: origin points at the repository on the account's server (HTTPS or SSH).
  • Clone of another repository, **repository without origin, not a repository**: shown and left as it is. Move the folder away or fix origin, then check again.

Later fetches of the dispatcher (base branch, branch updates) and the workers' pushes use the connected account the same way, so a fresh device needs no git credential helper and no SSH key, also for private repositories. A missing or expired token is reported in the dispatcher log and the app ("reconnect the account") instead of a git prompt.

Instead of cloning, Choose folder… points the assistant to the folder where the repository already lives. The folder is checked before it is saved: a clone of this repository is used; a missing or empty folder is saved and offered for cloning there; a clone of another repository, a repository without origin or a folder with other files is refused with that reason and nothing is saved.

By hand: clone the repository yourself into the clone folder.

6. Skill and agent instructions#

Check: the AGENTS.md in the local copy holds the current Gitoodo section.

Assistant: installs the Gitoodo skill on this computer if it is missing, and on request writes or updates the marked Gitoodo section of AGENTS.md in the local copy. Text outside the markers stays as it is, and nothing is committed: you review and commit the change yourself. This step does not hold back the first worker.

By hand: Settings → Skill, and copy the section shown there into AGENTS.md.

7. First worker#

Check: the dispatcher is registered as a background service (where the build may install one) and answers on its control socket and reports running workers.

Assistant: installs the dispatcher as a background service and starts it unless one already answers, so it keeps running after the app quits; the store build cannot install services and starts it from the app. The dispatcher logs to dispatcher.jsonl in the log folder (see logging). The assistant then waits for a worker. A worker starts as soon as an issue in an active repository carries the ready label. The setup is complete once a worker runs.

The dispatcher needs Unix sockets. On Windows this step explains that and stays open.

By hand: gitoodo dispatcher in a terminal, then give an issue the ready label. Details: dispatcher.md.

Final check#

The last page and the success page list the live state of everything the orchestrator needs (#601): classifier running as a service, every token readable by the services without a prompt, the classifier polling without errors, the local copy present with a matching origin, the dispatcher registered as a service and running. Each red item has one Fix button that opens the step that fixes it. The service step counts as done only once no token needs a keychain prompt, so the assistant never says "ready" while the services cannot work.

What the assistant never does#

  • It never commits and never writes configuration that is versioned in your repositories. It writes Gitoodo's own settings.json and orchestration.json, and only on request the marked Gitoodo section of AGENTS.md in the local copy.
  • It never shows a token, writes one to a file or log, or sends one to the app's frontend.
  • It never deletes or renames labels on the forge.
Docs version: dev