arizuko › products › Repo worker (Atlas) › setup

Repo worker setup

The setup makes a group from the GitHub product, connects GitHub webhooks through gitd, enables the GitHub connector and holds the merge.

group add makes the group from the product

On a running instance, make the group with the GitHub product. The persona and the facts of the agent belong to that group.

arizuko group -i <inst> add web:dev dev -p github

The command records the product selection for the group. Run arizuko package sync to install the files of the product.

The gitd package needs a token and a public host

Select the package:

arizuko package add -i <inst> catalog:gitd

Set these values in <data-dir>/.env:

package add installs the compose fragment and the webhook routes. Restart the instance:

sudo systemctl restart arizuko_<inst>

The GitHub connector gives the agent its tools

Copy the [[connector]] block from template/connectors/github.toml into <data-dir>/connectors.toml once. The hosted MCP server of GitHub gives the tools. Store a separate token for the folder, which the broker uses. The agent never receives that credential.

arizuko secret -i <inst> set dev GITHUB_TOKEN --value <token>
arizuko group -i <inst> grant folder:dev dev "mcp:github_<tool>"

The secret scope is the folder path, dev. The grant principal is folder:dev. Grant each tool that the agent needs by its exact name. Limit the token to the repositories and the operations that the agent needs.

A webhook source connects a repository to the group

Register a source. The command makes a sealed secret and writes the routes:

arizuko github -i <inst> add repo me/proj dev

Paste the printed URL and secret into Settings → Webhooks of the repository. Select application/json and the events that the agent must receive. A turn starts only on an explicit ask: an @mention, a review request or assignment to the bot, or a direct reply to a bot comment. Human conversation on a bot-authored pull request or issue maps to mention. Other activity goes to dev#observe as context. The addresses are github:me/proj/pr/<n> and github:me/proj/issue/<n>. Each pull request or issue has its own topic.

Select issue_comment, pull_request, pull_request_review, pull_request_review_comment and pull_request_review_thread for pull request conversations and state. Add check_run, check_suite and workflow_run for completed CI. CI and review-state events are observations. For an existing source, remove the message trigger rows and the issue mention trigger rows. Keep the pull request mention route and the observation fallbacks.

For an installed GitHub App, register an App source:

arizuko github -i <inst> add app <slug> dev

Paste the URL and secret into the webhook settings of the App. Install the App on the repositories that it must watch. One App source receives the events of all its installations. The registration does not give an outbound App token.

A hold grant stops the merge

Merge is the call that matters. A hold grant stops the call and asks you:

arizuko group -i <inst> grant folder:dev dev "hold:mcp:github_merge_pull_request"

A hold does not grant access to the tool. Approvals reach you in two ways, also with no chat platform: /approve <id> where you talk to the agent, and the link in the hold notice to /dash/approvals/.

A restart loads the connector

sudo systemctl restart arizuko_<inst>

facts/repo.md must hold your real commands

facts/repo.md ships as a placeholder, and you must replace it. Write the exact build, test and lint commands, name the generated directories that nobody edits by hand, and write what "done" means for a change.

The facts/ files of the product are examples, not package files, so arizuko package sync never rewrites them. Copy them once from the repository checkout:

cp -r ant/examples/github/facts /srv/data/arizuko_<inst>/groups/dev/

A wrong fact is worse than a missing one, because the agent cites it. A stale line in facts/ is a bug with a file name.

The agent must quote facts/repo.md

arizuko send -i <inst> dev "what are the build and test commands here?" --wait

A correct answer quotes facts/repo.md. If the agent guesses from the source tree, check that the product files are in the folder. Run product evaluations only against a throwaway instance.

The three flags and the token command are in Ship tests with it.