Settings
Configure models, Git access, merge strategy, review and agent behavior for a town
Open a town and click Settings to configure it. Settings apply to the whole town; some can be overridden per rig.
Git Authentication
Tokens used to clone and push to your repositories.
- GitHub Token: filled from the Hull GitHub App installation. You can paste a personal access token instead.
- GitLab Token and GitLab Instance URL: for GitLab repositories, including self-managed instances.
GitHub CLI
A personal access token used only for gh commands (pull requests, issues, reviews). Cloning and pushing still use the Git Authentication token.
Use a fine-grained token limited to the repositories the town works on, with read and write access to Contents and Pull requests. Add Actions if agents need to work with workflows.
Commit Identity
Set Author Name and Author Email to make commits appear as yours. The agent is added as co-author unless you turn on Disable AI co-authorship.
Environment Variables
Key and value pairs injected into every agent process in the town. Agent-level overrides take precedence.
Every agent in the town can read these values. Use test or development credentials, not production secrets.
Agent Defaults
| Setting | What it does |
|---|---|
| Default Model | The model agents use unless a role has its own. |
| Role models | Optional model per role: Mayor, Refinery, Polecat. |
| Small Model | A lighter model for auxiliary work such as titles and exploration. |
| Max Polecats per Rig | How many coding agents can work at once on one repository. |
Higher concurrency gets more done in parallel and uses more resources.
Convoys
| Setting | What it does |
|---|---|
| Stage convoys by default | New convoys wait for you to start them. On for new towns. |
| Default merge mode | Review then land: each bead merges into a convoy branch, then one landing pull request goes to your default branch. Review and merge: each bead gets its own pull request to the target branch. |
Merge Strategy
How reviewed work reaches your default branch.
| Strategy | Behavior |
|---|---|
| Pull request | The refinery opens a GitHub pull request or GitLab merge request for human review. The default for new towns. |
| Direct push | The refinery pushes merged code straight to the default branch. Quality gates are the only check. |
Refinery
| Setting | What it does |
|---|---|
| Quality gates | Commands the refinery runs before merging, such as npm test. |
| Refinery code review | Turn off to skip the refinery's review entirely. |
| Review mode | Rework requests: the refinery sends changes back as new work for a polecat. PR comments: the refinery posts review comments on the pull request (requires the pull request strategy). |
| Auto-resolve PR feedback | Sends a polecat to address unresolved review comments and failing CI checks on open pull requests. |
| Auto-resolve merge conflicts | Sends a polecat to rebase and resolve conflicts on open pull requests. |
| Auto-merge delay | Merge a pull request automatically this long after all checks pass and review threads are resolved: Off, immediately, 15 minutes, 1 hour or 4 hours. |
See Review and merge.
Container
Each town runs its agents in a container.
- Container Token: refresh the token agents use to reach Hull.
- Graceful Stop: agents save their work, then the container stops.
- Destroy Container: stop the container immediately. It restarts the next time work is dispatched.
- Automatic starts: pause or resume automatic container starts. While paused, scheduled work stays queued.
Hull Commons
Connect a personal town to a Hull Commons workspace so the Mayor can browse, claim and complete shared tasks. See Hull Commons settings.
Custom Instructions
Text appended to the system prompt for each role: Polecat Instructions, Refinery Instructions and Mayor Instructions (up to 2,000 characters each). Use them for conventions agents should always follow:
- "Use TypeScript strict mode."
- "Don't modify files in
vendor/." - "Every new function needs a unit test."
Debug
Copy diagnostic information to share with support@withhull.com. No sensitive data is included.
Danger Zone
Delete Town removes the town and all of its rigs. This can't be undone.
Per-rig settings
Open a rig's Settings to override town settings for that repository, including the default and role models, review mode, refinery review, auto-resolve options, auto-merge delay, merge strategy, convoy merge mode, polecat and refinery instructions, and maximum concurrent polecats.