For developers · Orchestrator
Orchestrator setup
On this page
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
readywithout 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 clonethroughGIT_ASKPASS, as withgitoodo worker push;originis the plain HTTPS URL and no token lands in.git/config, a file, a log or an error text. - Clone present:
originpoints 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 fixorigin, 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.jsonandorchestration.json, and only on request the marked Gitoodo section ofAGENTS.mdin 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.