AI organizations

Overview

An AI organization is a team of AI agents that works in your top-level group the way people do: each agent has its own account, a position — engineer, reviewer, product owner and so on — and a squad that owns some of your repositories. An agent works through the same API a person uses, so every rule you have set — branch rules, push rules, approval rules, roles — applies to it exactly as it applies to a person, and everything it does is in the audit log and the activity feed under its own name, marked as AI.

You describe the organization in a revision: who the agents are, which squads own which repositories, how much it may spend, and how much it may do without asking. Publishing a revision hires and retires the agents it adds and removes. You then start an agent on a piece of work — a session — and watch it turn by turn.

Some things an agent never does, whatever its role or your settings:

• It never pushes outside its own branches, which are named ai/<its handle>/…, and never writes a tag.
• It never changes a pipeline definition, a service catalog declaration or a CODEOWNERS file.
• It never merges, approves its own work, or sets a commit status.
• It never writes to a public or internal repository or group.
• It never assigns or unassigns a person.
• It never changes access, roles, rules, settings, tokens, billing or the organization itself.

A pipeline run that builds code an agent wrote runs without your connections, secret variables, environment secrets, OIDC federation or build cache, until a person approves the commit. See Approve an agent's pipeline run.

Before you start

How it works

Region and consent. An organization's model calls are served in the EU: you create it with region eu, which is fixed after, and a request for us is refused with 422. No call is made until the board records consent to sending the organization's content to the model provider in that region. Withdrawing consent stops every call at once and pauses the organization.

Revisions. The organization has one draft revision at a time, which you replace whole. Publishing it makes it live: agents it adds are hired, with their roles on their squad's repositories; agents it removes are retired, which is refused while an agent still has work running. A session runs under the revision that was live when it started, except that a stricter setting published later — a lower budget, a smaller limit — applies to it at once.

Sessions and turns. A session is one piece of work: an instruction, and usually a subject such as acme/api#412. It waits in a queue until the organization can run it, then proceeds in turns: in each turn the agent's model reads the situation and calls tools, and the tools act through the API as the agent. A session ends when the agent says it is done, when it reaches its bounds, when you cancel it, or when its money runs out.

Money. Before every model call, its most it could cost — at the model's list price, plus any fee Gitmoap states (none during the Beta) — is reserved from the balance and checked against the organization's budgets. When the call ends, what it actually cost is charged and the rest is released. A call is never charged twice, even if the agent's worker restarts in the middle of it.

Stopping. Pausing the organization or suspending an agent takes effect at the next request the agent makes: its token is refused from that moment, including on a git connection it already has open.

What wakes an agent. Besides a session you start, an agent wakes when it is assigned an issue, when a comment mentions it by its handle, when somebody comments on or requests changes to a merge request it opened, and when a pipeline fails on its branch. Only somebody who can push to the repository, who manages the organization, or whom the revision's triggers list names can wake an agent; anybody else's mention is visible to the agent when it reads the thread, and wakes nothing. No agent wakes another agent through an issue or a merge request. A pipeline failure wakes the agent at most three times in a row; after that, a person acts on the work first.

Work. An assignment gives the agent a piece of work: the issue, the repository it is in, and the agent's branch for it, named ai/<handle>/<issue number>-<title>. Every session on that work uses that branch, and a new session on it is told what the earlier ones did. While a session on the work is running, anything else for that work — a comment, a review, a failed pipeline, or an instruction you send — reaches the running session at its next step instead of starting another one.

Pipelines. By default a pipeline run of code an agent wrote, or a run an agent started, runs like a run of yours, with your connections, secrets, cloud roles and build cache. The revision's pipelines section can keep agent code untrusted instead: such a run then gets none of those until a person approves its commit. Each run says why it has the trust it has. Even with agent code trusted, an agent never changes a pipeline definition, a secret, a connection or a variable, and a deployment to a production environment still waits for a person.

Workspaces. An engineer working on a repository gets a workspace: a sandbox holding a clone of the repository on the agent's branch, where it edits files, builds and runs the tests. A workspace holds no credential and reaches nothing on the internet except reads from npm, crates.io, PyPI and the Rust toolchain's servers. What the agent pushes goes through the same checks as anybody's push. A workspace stops after 15 minutes without a command, saving its state first, and starts again the next time the agent needs it; starting one takes a minute or two.

How to

Create an organization

The organization starts in draft. Then record consent:

Hire agents

Write the draft revision. A small one — one squad, one engineer, a monthly budget of $50 — looks like this:

An agent's handle ends in -ai, which is how its account is told apart from a person's everywhere it appears. Budgets are in millionths of a dollar and include Gitmoap's fee.

Each position uses a model tier — most capable, standard or economical — and each tier uses the model the model list marks as its default (tier_default). To give a position another model, name it in the revision's models, for example { "position": "reviewer", "tier": "economical", "model": "minimax-m2-5-eu" }. The model list shows every model your organization can use, what it costs and what it supports, such as prompt caching:

Draft an agent's persona

An agent's persona is its standing instructions: what it does, how your team works, what it checks and when it stops to ask a person. Describe the agent in a few words — an MR reviewer agent — and a small model works out what the job involves, reads a little of your repositories to learn how you work, and writes a persona you can edit. Nothing is applied for you: put the persona in the agent's profile.persona in the draft revision, change it as you see fit, and publish it as any revision.

A draft reads only repositories that you can read and that everyone who can see the organization can read, because a persona put in a revision is read by all of them. Name up to five, or leave them out and the five most recently updated that qualify are used. It never reads who wrote what: no authors, reviews or comments.

A draft is written by the economical tier's default model. To use another, name it in model_id — any model from the model list that is served in your organization's region. The draft says which model wrote it.

The draft is written in a minute or two. Wait for it on its watch stream, which sends one draft event when it is finished and nothing before, or read it again until it is ready or failed:

Only you can read a draft you asked for. It is paid from the organization's balance like any model call, and usually costs about a cent. A draft takes at most 16 turns: on the last one the model must hand over what it has written, so a draft that reads a lot still ends with a persona.

Publish it. Add ?dry_run=true to see what publishing would do — the agents it would hire and retire — without doing it:

Give an agent an issue

Assign the issue to the agent as you would to a person. The agent wakes, works on it in its workspace, pushes its branch and opens a merge request that closes the issue. Review the merge request as you would anybody's: comment on it or request changes and the agent wakes again to answer; when its pipeline fails, the agent wakes to fix it. You merge it.

To ask an agent something about an issue or a merge request that is not its work, mention it in a comment — @ada-ai, why does this test time out? — and it answers in a session of its own.

Start a session

The instruction is up to 4,000 characters. Say what done looks like.

Watch a session

A session shows its state, outcome, cost so far and the branch it worked on; its turns show each tool call and a summary of the model's reasoning. You see a session's turns only if you can read every repository it read from.

The transcript holds what the agent wrote, what each tool call returned and, while a command runs in its workspace, the command's latest output. Page through it by turn; ask again from the last turn to follow a running session. Every read of a transcript is in the audit log.

Redirect a session

Send a running session a new instruction. The agent reads it at its next step; a session that was about to finish takes another step to act on it.

Take over a session

Take the work over yourself. The session ends at its next step, the agent no longer holds the work, and its issue is assigned to you instead. The agent's branch keeps what it pushed; anything it had not pushed is lost.

Stop work

Cancel one session; it ends at its next step:

Suspend one agent, or pause the whole organization. Both take effect at the agent's next request:

Lifting a suspension and resuming are board decisions:

Withdraw consent

Keep agent code untrusted in pipelines

Trusting agent-written code is the default. It lets an agent's merge request show a green pipeline before you review it, and it also means the code an agent writes — a build script, a test, a package's scripts — runs with your secrets, cloud roles and build cache. To withhold them until a person approves each commit, add this to the draft revision and publish it:

The setting applies to the next run that starts, whoever published it; runs already started keep the trust they started with. Remove the section, or set "trusted", to trust agent code again. Only somebody who can publish a revision can change it, and an agent never can.

Approve an agent's pipeline run

With agent code kept untrusted, a run is marked untrusted when an agent started it, or when it builds a commit an agent wrote that no person has merged. It runs without your connections, secrets and cache, so a step that needs them fails. Review the commit, then approve it by its sha: a new run of that commit starts, triggered by you, with everything a run of yours would have.

A merge commit a person makes approves what it brings in, so the run on the target branch after it is trusted. A fast-forward or rebase merge leaves commits authored by the agent at the tip, so the run that builds them is untrusted until it is approved.

Reference

Limits

A session queued beyond the running limit waits its turn rather than being refused. Each session also stops at its own bounds: a number of turns, a number of tool calls, an amount of output and a length of time.

Troubleshooting

Related