Skip to content

Docs

Getting started

From an empty account to your agents putting their changes on main, step by step. Each section is short: what it is for, what to click or type, and what you will see. In the examples, acme is your organization and api is a repository; use your own names.

On this page

1. Get started

  1. Open Sign up on the home page, enter your name, email and a password, and choose Create account. Your organization starts by adding prepaid credit in Billing: you pay only for what you use, and agents are free (no per-agent seats). At zero credit, paid work pauses and your code stays readable.
  2. Open the email we send you and click the link to confirm your address.
  3. If a team invited you, open the invitation link in your email and choose Accept invitation. You are now in the organization that invited you.
  4. To start your own organization as well, choose Create organization, give it a name and pick its region. Your code, issues, activity, logs and build files stay in that region, and the region cannot be changed later. Available now: India (Mumbai), run by Git A on AWS. More regions and clouds, and running Git A in your own cloud account or on your own servers, are coming.
  5. Add credit to start. A new organization is on Pay as you go with no credit: you can open it and look around, and pushes, new repositories, checks and agents start once credit is added. Right after you create it, its setup page shows Add credit to start: pick an amount (from the smallest top-up shown on the pricing page). You then see the exact price: the credits and any GST, with no fee for the way you pay. Where paying online is open for your billing country, pay on the payment provider’s secure page; otherwise choose Request credit and we email you payment details. Your credit is added when the payment arrives, and your organization can write at once. Fill in Billing, Profile too, so your invoice carries the right name and address.
  6. In your organization open Repositories and choose New repository. Every repository belongs to an organization and is private: only you and the people you add can see it.

You will see your new, empty repository. The next sections fill it. Two more things worth doing early:

  • Turn on two-step sign-in: open Your settings → Security → Two-factor authentication, scan the code with an authenticator app, and keep the recovery codes somewhere safe.
  • Browse your code: open a repository and choose Code to see its files and README, its commits and what each commit changed.

The quickest way: Fast-track setup

Right after you create your organization, Git A offers Fast-track setup. You can open it any time from your organization’s home page (Fast-track setup, top right). Pick the starting point closest to you and it walks you through, one screen at a time:

  • Just try it: a sample repository and one agent; see the agent put its first change on main in a few minutes. Nothing to install.
  • Cloud agents, no clone: your agents change code on Git A directly. Nothing to install.
  • Agents build, Git A deploys: agents propose, a machine of yours tests, approved changes go to production.
  • Agents on Git A, GitHub keeps a copy: GitHub gets main after every change, with the same commit IDs.
  • Move my GitHub repository: your full history on Git A, every commit ID unchanged.
  • Your own agent system (webhooks): several agents, a webhook to your factory, and changes that land by themselves when your required checks pass on them together with the latest main.
  • Agent factory: connect a model, create an agent and give it an issue; it writes the code and tests and hands the change back for your review (see Hand an issue to an agent).

What to expect:

  1. Each step asks only what it needs, with choices to pick rather than formats to type.
  2. Continue opens only when the step is really done. You see what Git A is waiting for, for example Waiting for your agent to connect…, and it turns green the moment your agent makes its first request. The same goes for your runner coming online, your first check passing and a test message reaching your factory.
  3. When you connect an agent, its key is shown once, next to ready-made settings for Claude Code, Cursor, Codex and the ga command line. Copy them before you move on.
  4. One click adds the house rules for this repository to AGENTS.md, CLAUDE.md or a Cursor rule, so your agent knows from its first task how to work here: it calls get_started first, then follows how changes reach main. Only the Git A part is added; the rest of the file stays yours.
  5. You can leave at any time. Your place is kept (never your keys), and when you come back every finished step is checked again.
  6. At the end you get a summary with links to everything that was set up and what is left to do.

Quickstart for your AI app

Pick the app you use. Each quickstart takes you from a new account to your agent's first change on main in a few minutes, through Fast-track setup, with nothing from Git A to install. To follow every change on its way to main inside your app, see the live Git A panel.

Claude (web, desktop, phone)

  1. Sign up, create your organization and add credit (Get started).
  2. On your organization's home page open Fast-track setup (the setup page), choose Just try it and follow its screens. On Connect your agent, pick Claude (web, desktop, phone).
  3. In Claude on the web or in the desktop app, open Customize, then Connectors, and choose Add custom connector. Paste https://git--a.com/mcp, choose Add and then Connect. Sign in to Git A if asked and choose Allow. It then works in Claude on your phone too.
  4. Paste the task the setup page shows into a new chat. Claude adds one line to README.md and lands it, as you. The setup page shows On main with the line it added.

ChatGPT

  1. Sign up, create your organization and add credit (Get started).
  2. On your organization's home page open Fast-track setup (the setup page), choose Just try it and follow its screens. On Connect your agent, pick ChatGPT.
  3. In ChatGPT, open Settings, then Apps, and turn on Developer mode under Advanced settings. Choose Create, name it Git A, paste https://git--a.com/mcp and choose OAuth as the way to sign in. Sign in to Git A when asked and choose Allow.
  4. In a new chat, pick Git A from the tools and paste the task the setup page shows. ChatGPT adds one line to README.md and lands it, as you. The setup page shows On main with the line it added.

Claude Code

  1. Sign up, create your organization and add credit (Get started).
  2. On your organization's home page open Fast-track setup (the setup page), choose Just try it and follow its screens. On Connect your agent, pick Claude Code.
  3. Choose Create the agent and its key (it asks for your password once). Run the one command the setup page shows in a terminal, in the folder you start Claude Code in. Start Claude Code there, say yes when it asks to trust the folder, and type /mcp: gita should say connected.
  4. Paste the task the setup page shows into Claude Code. It changes one line and proposes it for main.
  5. When the setup page says the change waits for your approval, choose Approve and land. You see On main with the change's number.

Cursor

  1. Sign up, create your organization and add credit (Get started).
  2. On your organization's home page open Fast-track setup (the setup page), choose Just try it and follow its screens. On Connect your agent, pick Cursor.
  3. Choose Create the agent and its key (it asks for your password once). In Cursor, open Cursor Settings, then MCP, and add a new global MCP server. Paste the setting the setup page shows into the file Cursor opens and save it. Say yes when Cursor asks to trust Git A: gita-agent gets a green dot.
  4. Paste the task the setup page shows into Cursor's chat. It changes one line and proposes it for main.
  5. When the setup page says the change waits for your approval, choose Approve and land. You see On main with the change's number.

Codex

  1. Sign up, create your organization and add credit (Get started).
  2. On your organization's home page open Fast-track setup (the setup page), choose Just try it and follow its screens. On Connect your agent, pick Codex.
  3. Choose Create the agent and its key (it asks for your password once). Add the three lines the setup page shows to config.toml in the .codex folder of your home folder, save it, then start Codex again. The Codex app, its command line and its editor extension all read it. Say yes when Codex asks to trust the folder, and type /mcp: gita-agent is listed.
  4. Paste the task the setup page shows into Codex. It changes one line and proposes it for main.
  5. When the setup page says the change waits for your approval, choose Approve and land. You see On main with the change's number.

VS Code with Copilot

  1. Sign up, create your organization and add credit (Get started).
  2. On your organization's home page open Fast-track setup (the setup page), choose Just try it and follow its screens. On Connect your agent, pick VS Code with Copilot.
  3. Choose Create the agent and its key (it asks for your password once). Save the setting the setup page shows as .vscode/mcp.json in the folder VS Code has open. VS Code asks for the key once: paste it, and say yes when it asks to trust Git A.
  4. Open Copilot Chat in Agent mode and paste the task the setup page shows. Copilot changes one line and proposes it for main.
  5. When the setup page says the change waits for your approval, choose Approve and land. You see On main with the change's number.

2. Bring your team

  1. In your organization open Members and choose Invite member.
  2. Enter their email and pick a role: Owner, Admin, Billing manager or Member.
  3. They get an email and follow Get started (section 1).

Joining the organization opens no repository. Every repository is private: only the person who created it and the people they add can see it. Organization owners and admins manage members and billing, not repositories.

  1. To let someone in, the repository’s creator opens the repository, then Settings → People.
  2. Enter their username, pick a role (read, triage, write, maintain or admin) and choose Add person. They can use it at once.
  3. To take access away, remove them from the list. It ends on their very next request.

If the creator leaves the organization, the organization’s owner takes the repository over.

3. The ga command line

ga is Git A’s command line. It works like git: the same commands and the common options, so what you already know carries over. It can also open and merge pull requests and put changes on main.

On a paid plan, download it from Downloads in the app: open your organization, choose Downloads, and copy the one-line install command into a terminal. It installs ga and ga-runner and shows their version when it is done. You do not need ga to use the website, or to connect an agent over the web (section 5).

What your computer needs. The downloads are for 64-bit Linux (Intel/AMD, and ARM where Downloads lists it) with glibc 2.35 or newer: Ubuntu 22.04, Debian 12 or newer, and other Linux systems of the same age. They do not run on older systems such as Ubuntu 20.04, Debian 11, RHEL 8 or Amazon Linux 2, or on Alpine Linux. To see what a computer has, run ldd --version: the first line ends with its glibc version. Downloads shows the exact need of the current version, and the installer checks the computer first and changes nothing when the tools cannot run there.

Git A keeps its own files in a .gita folder, and the files to ignore are listed in .gitaignore (like .gitignore). Before you send or fetch anything, give ga your own key:

  1. Open Your settings → Personal access tokens → New token.
  2. Pick the repositories, tick Write if you will send changes, choose a lifetime and create it.
  3. Copy the key (it starts with gat_ and is shown only once) and set it as GITA_TOKEN, as in the first line below.
bash
export GITA_TOKEN=gat_…                    # your personal key: Your settings → Personal access tokens → New token
ga clone https://git--a.com/acme/api && cd api
ga switch -c fix-parser
ga commit -am "Fix the parser"
ga push -u origin fix-parser
ga pr create --title "Fix the parser"
ga pr merge 12 --squash

ga pull and ga push need no branch names. A clone, and a branch you check out from the server, remember where they came from. A branch you made yourself pulls from, and pushes to, the server’s branch of the same name; ga says so in one line and gives the command that remembers it. When the server has no branch of that name yet, ga tells you the exact command to run instead. A branch that already follows another server keeps following it. A forced push (ga push -f) never picks the server’s branch for you: name the branch yourself (ga push -f origin <branch>), so nobody’s work is overwritten by surprise.

For agents: JSON output

Add --json to any ga command and it answers with one JSON document instead of text, so an agent or a script reads the result directly, with no guessing from text output. It works before or after the command name: ga --json status and ga status --json are the same.

  1. Run the command with --json. You get one JSON document on standard output, for example {"branch":{"head":"main",…},"files":[…],"clean":false} for ga status --json.
  2. status, log, show, diff, branch, tag, remote, config, commit, clone, fetch, pull and push give named fields (files, commits, branches, ref updates). Workspaces, landing, proposals and pull requests give their usual JSON answer. Every other command gives {"command","exit_code","lines","messages"}.
  3. If something goes wrong, the command exits with a non-zero code and the error comes as one JSON line on standard error: {"error":{"code":"read_only","message":"…","hint":"…"}}. The hint says what to do next.

The code never changes wording, so your agent can act on it: not_found, conflict, auth_required, forbidden, read_only, limit_reached, rate_limited, unsupported, invalid_argument, usage, not_a_repository, locked, network, unavailable, server_error or failed. Two that look alike: forbidden means your token cannot do this, for example a read-only token trying to push (use a token that can write), while read_only means the organization is read-only until credits are added (none were added yet, or they are used up): add credits on its billing page, then try again.

JSON output is always plain ASCII: any other character arrives as a \u escape, so a program reading it on any system and in any language setting never fails on an unexpected character. When ga writes to a pipe or a file, when NO_COLOR is set, or when you add --plain, it also prints no colours and no decorative symbols.

bash
ga status --json                       # branch, changed files, untracked files
ga log -5 --json                        # the last five commits, with author, date and message
ga diff --json                          # each changed file with lines added and removed
ga push --json origin my-branch         # what moved on the server, or the error and its code

4. Bring your code from GitHub (and take it back)

You need the ga tool for this (section 3).

Your history comes across complete, and every commit keeps exactly the same ID it has in Git and on GitHub. You can send it back to GitHub (or any Git server) at any time.

  1. Create an empty repository on Git A (section 1, step 5).
  2. For a private GitHub repository: on GitHub open Settings → Developer settings → Personal access tokens and make a token that can read the repository (to export back, one that can also write). Then run export GITA_GITHUB_TOKEN=ghp_….
  3. Copy the project from GitHub with ga import. It creates a new folder named after the repository.
  4. Point it at your Git A repository and send everything up with ga push.
bash
ga import https://github.com/acme/api     # makes the folder ./api, same commit IDs as on GitHub
cd api
ga remote add origin https://git--a.com/acme/api
ga push -u origin main

A project that is already on your computer works the same way: ga import ~/src/api makes a new folder, ~/src/api-gita, next to it and leaves your Git folder untouched.

To send your history back to GitHub (or any Git server), use a GitHub token that can also write (step 2), then run:

bash
ga export https://github.com/acme/api     # every branch and tag, same commit IDs

5. Connect an agent

Using Claude on the web, in the desktop app or on your phone? You need no key for that: see Use Git A from Claude below.

An agent is a helper account that belongs to your organization. A person on your team is responsible for it, and it can never do more than that person. Each agent gets its own key, so you always know which agent did what.

  1. In your organization open Agents and choose New agent.
  2. Give it a name, choose the person responsible for it (Sponsor) and pick the repositories it may use.
  3. Tick Can write so it can make changes. Tick Can put changes on main so it can finish its work by itself in its own space on Git A. This box does not decide whether a person sees a change first: each repository sets that under Settings, Agent changes to main. With Ask me a person approves every agent change before it reaches main. With Auto when checks pass it reaches main by itself once your required checks pass on it together with the latest main (section 6). No checks are required at first, so until you choose some a person approves every change, even with Auto. The one exception is a repository that lets agents put changes on main directly, with no approval and no required checks.
  4. If the agent is only needed for a while, set when it expires. Then choose Create agent.
  5. Open the agent, choose New token, then Create token. Copy the key (it starts with gat_): it is shown only once.
  6. Give the key to the agent as GITA_TOKEN: set it in the terminal where you start the agent, for example export GITA_TOKEN=gat_….
  7. Add Git A to the agent with MCP, as shown below.

Your agent gets a guide for your repository the moment it connects. It learns how changes reach main here, what it may change, whether your checks can run, and what to do next, so you do not have to explain Git A to it. The guide never contains your keys or secrets.

Want the guide saved in your repository too? Open the agent, choose Agent guide, pick your tool (Claude Code, Codex and others, or Cursor) and choose Add to repository, or Copy. From a terminal: ga agent-instructions --write.

Set your repository up for every AI app at once: in your clone, run ga setup agents. It adds the settings Claude Code, VS Code with Copilot, Copilot CLI, Cursor, Codex, Devin, Zed, Kiro and Antigravity read, with your repository’s Git A address and no keys. Files you already have keep everything in them. Commit the new files, open the repository in your app, say yes when it asks to trust the folder and Git A, and sign in once. Repositories made with Just try it come with these settings.

Check the connection: the same page shows green ticks when your agent can read, can make changes, and has a runner for its checks, and says when your agent last connected.

MCP for agents

MCP is the standard way AI coding tools such as Claude Code connect to other services. Pick one of these:

  • Over the web (nothing to install): save the setting below as .mcp.json in the top folder of the project where you start the agent, replace acme/api with your organization and repository, and restart the agent.
  • Claude Code: run the one command instead, with your organization and repository in place of acme/api.
  • On your computer: the same tools run locally through ga, if you have it (section 3).
.mcp.json · over the web (nothing to install)
{
  "mcpServers": {
    "gita": {
      "type": "http",
      "url": "https://git--a.com/api/v1/repos/acme/api/mcp",
      "headers": { "Authorization": "Bearer ${GITA_TOKEN}" }
    }
  }
}

Tell your agent to call get_started first; it is listed first in the tools. From a terminal, ga get-started shows the same guide.

With the web setting the agent needs no copy of the code on its machine: it reads the repository on Git A, makes its changes in its own space there, and puts them on main (or opens a pull request). To see everything an agent can do, run ga mcp tools.

To stop an agent, open it and revoke its key, or choose Suspend: it loses access at once, and its history stays.

Many agents at once, even on the same files

Your agents never take turns. Each agent, and each helper agent it starts, works in its own lane: its own copy of the repository and its own branch. Many agents can work at the same time, in the same files, and none of them waits for another.

  1. Agent connected over the web: it opens its own lane with ws_open, changes files there and finishes with land. Nothing to download.
  2. Agent that builds or tests on your computer: one folder per agent. In a copy of the repository run ga worktree add ../fix-login -b agent/claude-1/fix-login origin/main, work only in the new folder, then ga add -A, ga commit -m "Fix the login timeout" and ga propose.
  3. When the changes reach main, edits that do not touch each other go in together by themselves, even in the same file. Edits at the same place or on neighbouring lines usually both land too. When they cannot, or when two agents change the very same lines, one of them hears back, with the files and lines named. It redoes its part on top of the other one, and nothing it wrote is lost.
  4. No waiting: after each push the checks your workflows define run on Git A machines (or your own runners), side by side. Your agent keeps the proposal's number, starts its next task and checks back later. Other agents and deploys never hold it up. No workflows yet? Your agent runs the tests itself before it proposes.

You do not have to explain any of this. Your agent learns it the moment it connects, and get_started gives it one line to hand to each helper agent it starts. Avoid the old habits: several agents in one folder, splitting the work by file, or making one agent wait for another. On Git A they only slow your agents down.

Use Git A from Claude, on your computer and your phone

Connect once on the web and Git A works in Claude everywhere you use it. You sign in with your own Git A account; no key to copy.

  1. On claude.ai (or in the Claude desktop app), open Customize, then Connectors (claude.ai/customize/connectors), and choose Add custom connector.
  2. Paste https://git--a.com/mcp and choose Add.
  3. Choose Connect. Sign in to Git A if you are asked, check the repositories it will use, and tap Allow.
  4. That's it. Git A now works in Claude on the web, in the desktop app and in the Claude app on your phone, and stays connected: you do not sign in again every day.

Claude can use the repositories you allow, and never more than you can yourself. Leave them all ticked and Claude also gets every repository you create or join later, with no need to connect again. Untick some and it keeps to the ones you chose. If you lose access to a repository, Claude loses that one too and keeps the rest. Tick Read only on the Allow screen if Claude should look but not change anything. Add the connector on the web or desktop first; it then appears in the Claude app on your phone by itself.

To disconnect, open Git A, go to Settings, Tokens and apps, Connected apps, and choose Remove. It stops at once. We also email you each time an app is connected, so you always know.

Watch your agent's change reach main, live, in your AI app

When your agent proposes a change through Git A, the Git A panel shows its progress in the app you are working in: proposed, checks running and passed, tested with the latest main when your repository requires checks, waiting for you when you chose Ask me, and on main. Each step shows up as it happens.

  1. Claude on the web and desktop, ChatGPT and VS Code: add Git A as a connector with https://git--a.com/mcp (see above). The panel shows in the chat by itself the next time your agent proposes a change. There is nothing to install.
  2. Claude Code: with the ga tool (section 3), run ga badge on once, then start a new Claude Code session. The panel sits above your prompt and follows the proposal of the branch you are on. To remove it, run ga badge off.
  3. Other apps, such as Cursor: add the same address as an MCP server. Apps that can show the panel draw it in the chat; the others get a one-line status with the same steps.

Hand an issue to an agent

Write an issue, hand it to an agent, and get back one finished change to approve. The agent works on a fresh machine of its own: it plans the work, writes the code and its tests and runs your checks, and a separate review checks the change against what the issue asks for. The machine is gone afterwards. Everything starts in your organization under Agent factory. This guide takes you through it from the beginning:

  1. Connect your model (once for your organization)
  2. Create an agent
  3. Write the issue
  4. Hand it to the agent, in the way that suits you
  5. Watch it work and answer it when it asks
  6. Review and land the change, or let it land by itself
  7. What it costs
  8. When something goes wrong

1. Connect your model

An owner or admin of the organization does this once. Every agent of the organization can then use it.

  1. Open Agent factory and choose Models at the top (while you set up, the first step on the home page has a Connect a model button to the same page). It is always there, also when your agents run their own program and need no model yet.
  2. Pick your provider's tile: Anthropic, OpenAI, Google Gemini, Google Vertex AI, Amazon Bedrock, Azure OpenAI, OpenRouter, Mistral, xAI, DeepSeek, Groq, Together AI or Fireworks AI. The usual model of that provider is already picked; choose another one if you like.
  3. Have your own LLM gateway, such as LiteLLM? Pick Your own gateway, say whether it speaks the OpenAI or the Anthropic format, and give its address, its key and any extra headers it needs. If it is reachable only inside your network, choose Your runners under Where it runs.
  4. Run a model on your own machine? Pick A model on your machine (Ollama or vLLM). Agents that use it run on your own runners (section 10).
  5. Paste your key and choose Save and test. You see each step of the test as it happens, and when it works, for example, Anthropic works. with a Create an agent button.
  6. Your key cannot use the picked model (your provider retired it, or your account has no access to it yet)? The test says This key cannot use that model and lists the models your key can use. Pick one and choose Use this model and test: the test runs again at once. Under Your models, Change model gives a connection another model at any time.

Your provider bills you for the model on your own account, as usual. The agent never sees your key.

2. Create an agent

  1. Choose Create an agent (or open Agents, then New agent). Give it a name, for example builder, and choose the person responsible for it.
  2. Tick It takes issues and works on them with a model you connected and pick its Model.
  3. Under Repositories, tick the ones it works on. It works on its own branches, and every change it makes comes to you as a proposal.
  4. Under When it's done, choose Ask me (you approve every change) or Land by itself when checks pass.
  5. Keep Every change comes with tests ticked, then choose Create agent. You see how ready its repositories are for agents, and what to do next.

On the agent's page, under Model and work, you can change more:

  • Program: what runs your agent. Claude Code, Codex, Gemini CLI, Goose, OpenCode, your own command (one line, run in the repository) or your own container image. Your own command or container gets the task as files. Left as it is, the agent uses the usual program for its model.
  • Where it runs: on Git A machines, or on your own runners with the label you give (section 10). An agent works where its model connection says; with your own command or container you choose it on the agent's page.
  • Instructions: plain words it follows on every task, like you would tell a new teammate.
  • Limits: choose Change limits to cap what one run may use, such as Longest run in minutes and Model estimate per run in US dollars. An agent can only make these stricter than its organization.

From a terminal: ga factory agent create builder --repos acme/api --connection anthropic --program claude-code (add --auto to let it land by itself when checks pass).

3. Write the issue

The agent works from what the issue says, so write it the way you would for a new teammate. Open the repository, choose Issues, then New issue.

  1. In the title, say in one line what should change, for example Show an error when the password is wrong.
  2. In the text, say why, where to look if you know (a page, a file, a command), and what must keep working. Paste the exact error message if there is one.
  3. End with the acceptance criteria: how you will know it is done, one line each, for example The login page shows Wrong password and keeps the email filled in. The agent plans its work from them, and the review checks the change against each one.

4. Hand it to the agent

Pick the way that suits you; each one starts the same work. To start an agent you need at least the triage role on the repository (owners can change that under Agent factory, Who can do what, Start agents on a repository).

Assign the issue to the agent
  1. Open the issue (or a new one) and pick your agent under Assignees. Below the list you see Assigning builder starts it.
  2. That is all. A status line appears under the issue's title, for example builder is working: writing the spec · 2 min.
  3. Changed your mind? Remove the agent from Assignees and its work is cancelled.

On your first visit to Agent factory, its last step does the same: pick an open issue (or write what to do) and choose Start builder.

Mention the agent in a comment
  1. On the issue, post a comment whose first line starts with the agent's name and says what to do, for example @builder fix this and add a test for an empty password. The agent starts on the issue with your words.
  2. On a pull request, @builder and what to do starts work from that pull request's branch. @builder review reviews it, @builder security looks for security problems, and @builder describe writes its title and description.
  3. @builder help answers with everything it understands. /approve approves the plan it asked you about, /stop stops its work and /retry tries again after a problem.

Editing an old comment starts nothing: post a new one.

From a terminal

With the ga command line (section 3), inside a copy of the repository. Anywhere else, add the repository, for example -R acme/api.

bash
ga issue assign 12 builder                # give issue 12 to builder, the same as Assignees
ga issue create --title "Show an error when the password is wrong" --body "..." --assignee builder
ga factory run 12 --agent builder         # the same as assigning it
ga factory ask --agent builder "Add a dark mode switch to the settings page"   # becomes an issue, and builder starts
ga factory tasks                          # your agents' tasks in this repository

New to all of it? One command does steps 1 and 2 and hands over the first open issue: put your model key alone in a file and run ga factory start --key-file ~/anthropic-key.txt in a copy of the repository. The key never goes on the command line.

From your AI app
  1. Add Git A's second address, https://git--a.com/api/v1/platform/mcp, to your AI app with an agent's key, the same way as in MCP for agents. In Claude Code: claude mcp add --transport http gita-platform https://git--a.com/api/v1/platform/mcp --header "Authorization: Bearer $GITA_TOKEN"
  2. Ask in plain words, for example Give issue 12 in acme/api to builder, or Ask builder to add a dark mode switch to acme/api. Your app starts the work, in the name of the person responsible for the key's agent.
  3. Ask How is builder doing on issue 12? at any time: your app reads where the task stands.
From Slack, Teams, Discord or Google Chat

An admin connects your team chat once: open Agent factory, Connectors, and follow the numbered steps on the card for Slack, Microsoft Teams, Discord or Google Chat. On the card you also pick the repository the agent works on when a message names none, and the agent.

  • Slack: invite Git A to a channel (/invite @Git A), then write @Git A fix the login timeout in acme/api, or use the command /gita fix the login timeout in acme/api.
  • Microsoft Teams: in the channel, write @Git A fix the login timeout in acme/api.
  • Discord: type /gita fix the login timeout in acme/api.
  • Google Chat: in the space, write @Git A fix the login timeout in acme/api, or send it to Git A in a direct message.

Git A answers at once, for example On it: issue #31, task 52. Its progress, the plan to approve and the change to review follow in the chat. Git A knows you by the e-mail address you use in both places. If it does not, it says so, and you link your chat account once:

  • Slack and Discord: send /gita link. Git A answers with a code only you see; enter it in Git A under Agent factory, Connectors, Link your chat account within 15 minutes. Discord always needs this link once.
  • Google Chat: send link to Git A in a direct message, never in a space, and enter the code the same way.
  • Microsoft Teams gives no link code, because it shows every answer to the whole channel. Use the same e-mail address in Microsoft Teams and in Git A, and Git A knows you.

Only enter a code you asked for yourself. Other commands: status, stop and help.

From a GitHub, Linear or Jira issue

GitHub. Bring the GitHub repository's issues in once, then a label on GitHub starts the agent:

  1. In your Git A repository, open Issues and click Bring issues from GitHub (see Issues).
  2. Tick Keep in sync, then Start the default agent from a GitHub label. The label is git-a unless you type another one.
  3. On GitHub, add the label git-a to an open issue. Your organization's default agent starts on it, in the name of the person who turned on Keep in sync. With a GitHub token saved under Connectors, GitHub issues, the GitHub issue gets the link and is closed when the change lands.

An admin picks your organization's default agent under Agent factory, Connectors, Default agent: issues labelled git-a in GitHub, Linear or Jira go to this agent (a Linear or Jira card that names its own agent uses that one). If the issue in Git A says none is set, its message links to that card.

Linear and Jira. An admin opens Agent factory, Connectors, and follows the steps on the Linear or Jira card, with the repository the issues come to and the agent. Then, in Linear or Jira, any of these starts the agent:

  • assign the issue to the account that stands for your agent (you name it on the card);
  • give it the label git-a;
  • or comment @git-a and what to do.

The issue comes over to your Git A repository and the agent starts. Linear or Jira gets a comment at each step and the proposal's link, and the issue moves to In Progress and then to Done. People whose Linear or Jira e-mail address is a member's can start work. The card's switch People without a Git A account may start work lets anyone in your Linear or Jira start work, in the name of the person who set up the connection. Leave it off unless that is what you want.

5. Watch it work

  • On the issue: the status line under the title, for example builder is working: writing the spec · 2 min, links to the task page.
  • The task page shows Progress (click a step to see what the agent did in it), the plan, the acceptance criteria with what the review found, Checks and rules and Cost. Agent factory, Tasks lists them all.
  • From a terminal: ga factory task 52 --watch follows task 52 live until it needs you or ends.
  • In your AI app: once the agent has handed back its proposal, ask your app (with Git A connected) how proposal 18 is doing. The Git A panel shows its progress in the chat (see the live Git A panel).

When it needs you. The agent asks only when it must, on the issue (or in your chat thread), and you also get an email:

  • A plan to approve: Here's my plan for this. Reply /approve to go ahead, or tell me what to change. with its summary, acceptance criteria and tasks. Reply /approve, choose Approve spec on the task page, or run ga factory approve-spec 52. Any other reply tells it what to change in the plan.
  • A question: I need your answer to continue: … Reply on the issue, choose Answer on the task page, or run ga factory answer 52 "Use the EU date format".

6. Review and land the change

Before it hands anything back, the agent opens the proposal, waits for your checks and tries to fix what fails. Then:

  1. It comments that this is ready for your review, with the proposal, the files changed, the tests it added and the checks that passed.
  2. Open the proposal and read the change, the test results and what the review found.
  3. Choose Approve and land (while checks still run: Approve: land when checks pass). It reaches main, and your workflows deploy it as they always do.
  4. Want something changed? Comment on the proposal or the issue, or leave a review that asks for changes. The agent changes the same proposal and comments what it updated. After a set number of rounds it stops and tells you how to take over.

Or let it land by itself. Set the agent to Land by itself when checks pass and the repository's Agent changes to main to Auto when checks pass. The change then reaches main on its own once your required checks pass on it together with the latest main (Require checks before changes reach main), and the agent comments that it landed. A deploy whose environment asks for a person still waits for one (section 11).

7. What it costs

  • The model: Your provider bills you for it on your own account, as usual. The task page's Cost shows an estimate at your provider's list prices (a gateway whose use Git A cannot read shows none).
  • The machines: Git A bills the machine minutes and storage of each task from your prepaid credit. On your own runners, Git A charges no machine minutes.
  • The agents: free, with no per-agent seats.
  • Spending limits: under Agent factory, Guardrails, set Model spend per run, Model spend per day, Machine minutes per day and a Monthly spend alert. Each agent's Limits can only be stricter.

Every charge is shown where you already look: See what everything costs.

8. When something goes wrong

  • No model connected. The issue says builder has no model yet, so I can't start. Set it up: … Open the link and give the agent a model (steps 1 and 2). Then remove it under Assignees and pick it again, or comment @builder with what to do.
  • No credit. I can't start yet: your credits cannot start a Git A machine right now. Add credits in Settings → Billing, and the agent starts by itself once they are in. Or let it run on your own runners.
  • It asked you something. I need your answer to continue: … means it waits for you: answer as in step 5.
  • A check failed. The agent first tries to fix a failing check itself. If it cannot, it stops and says why: I stopped: … with the check that failed. Fix what it names, then comment /retry, choose Retry on the task page, or run ga factory retry 52. To finish it yourself, choose Open locally on the task page.
  • Nothing started. The issue says why, for example that you need the triage role, that the limit of new tasks was reached (and when the next one can start), or Every agent of your organization is stopped right now, so nothing starts. An admin chooses Let agents work again on the Agent factory page.

6. Put changes on main

You need the ga tool for this (section 3), unless your agent does it for you over the web.

Putting a change on main is called landing. When an agent lands a change, it goes onto main even if other agents landed theirs a moment earlier: no rejected push and no pull-and-try-again loop. Pull requests still work too, for changes a person should review first (section 8).

There are three ways to land a change:

  1. From an agent: ask it to make the change. With the setting from section 5 it opens its own space, writes the files and lands them by itself.
  2. From a terminal, without a local copy: use a workspace on Git A (section 7).
  3. From a local copy: commit, send your branch, then land that commit:
bash
ga switch -c fix-parser
ga commit -am "Fix the parser"
ga push origin fix-parser
ga land --commit $(ga rev-parse HEAD) -m "Fix the parser"

If another agent added something at the very same place a moment earlier, Git A usually keeps both and lists the file under kept both. If your repository has required checks, they run on the combined result before it reaches main. If both agents changed the very same lines, Git A tells your agent right away which lines clash and with which change; nothing anyone landed is lost. Want Git A to never combine a file? Add generated/** -merge to .gitaattributes.

Require checks before changes reach main

Two changes can each pass their own checks and still break main together: one agent renames something while another starts using the old name. Required checks stop that. Once you require checks, changes reach main only when the combined result passes: Git A tests each change together with the latest main, and what lands is exactly what passed. If main moved while the checks ran, the change is tested again on the new main before it lands. A new repository requires no checks until you choose some: until then a person approves each change, and nothing is tested together.

  1. Make sure main has a workflow with the checks you trust (section 10). Its checks have names like CI / test: the workflow, then the job.
  2. Open your repository, choose Settings, then Required checks on main.
  3. Tick the checks that must pass (a workflow name alone means all of its jobs) and choose Save. Pick checks that test your code. A job that deploys (one with an environment) is never offered: required checks run on changes before they land, and those never deploy. If you name one anyway, Git A says so and saves nothing.
  4. Under Agent changes to main choose Auto when checks pass if changes should land by themselves once they pass, or keep Ask me to approve each one first. Either way, nothing lands until the required checks pass on it together with the latest main.

From a terminal (an admin of the repository):

bash
ga propose policy --require "CI / test" --auto   # require a check, let changes land by themselves
ga propose policy                                # see what main requires

What you will see on a proposal:

  • Testing it together with the latest main: its required checks are running on the combined result.
  • main moved, re-checking: another change landed first, so it is tested again on the new main. The older check stops at once, with a note that a newer check took its place: it never counts as a failed check, never turns the proposal red, and uses no more machine time.
  • CI / test: running 6 min, step 4 of 9: while checks run, each one shows how long it has run and which step it is on. After a new push it says the checks restarted for the new commit, and a check that cannot start says why.
  • Passes alone but fails together with the latest main: the failing check is named. The agent merges main into its branch (ga fetch origin, then ga merge origin/main), fixes it and pushes; the proposal updates by itself.
  • Required check … did not run on the change together with the latest main: your workflow skips that job there (for example a job that runs only for pushes to main). A skipped check never counts as passed, and neither does a job whose every run: step is switched off for proposals (for example if: github.event_name == 'push' on each step, directly or through an env value). An admin changes the job so it also runs for proposals, or picks another required check, then chooses Check again.
  • No checks are required, so a person approves: Auto is on, but main requires no checks yet.
  • Already in main: the same change landed from another proposal first, so this one closed with no commit, and nothing ran or deployed for it.
  • Landed as #65 (main de52cc3): you proposed a commit that already landed, so nothing new was opened. A branch with no changes compared with main says Nothing to land instead, and nothing is opened.
  • Passed on re-run: a check failed first and passed when it ran again on the same commit, so the test may be flaky. If a check fails for a reason that has nothing to do with the change, the agent can run it again without a new commit: ga propose rerun. This works for the change's own checks and for the required checks on the change together with the latest main. A passing re-run counts, up to two re-runs per check on the same commit (testing a failed change again on the same main counts too); after that the agent fixes it and pushes. A person's re-run always counts. When main requires checks, a change that passed only on an agent's re-run is still tested once more together with the latest main before it lands. Re-running a failed check from its run page or with ga run rerun counts the same way and tells you so, for example “Counts for proposal #86: it lands by itself if this passes”.

A required check counts only when your own workflow ran it, it did its work and it passed. A check result someone posts from outside your workflows, or a run someone started by hand, never stands in for it.

Once main requires checks, every way onto main goes the same way. A direct ga push to main, and Update branch on a pull request that would change main, are refused with what to do instead; ga land, a workspace landing and the Merge button become a proposal that lands when the combined result passes. If a pull request is pointed at main while it is being merged, the merge stops and is decided again for main. Main itself can never be deleted, not even by merging it into another branch, so it cannot be made again from untested work. A branch named like main in different letter case (MAIN, Main) is refused too, on every computer, and so is any branch or tag whose name differs from an existing one only in letter case. When you merge a pull request into main with Merge after reviewing it, the approval holds for the commit you saw: if new commits arrived meanwhile, the merge asks you to look again. If main kept moving and a proposal paused, choose Check again on its page or run ga propose again. Agents can never change the required checks, and a change to your workflow files always waits for an admin.

Your team merges into its own branch first (such as dev)

Many teams send every change to a branch like dev first and move it to main later. Proposals work there too, with the same promises as on main: the change is tested together with the latest dev, the checks dev requires must pass, the approvals you set apply, and exactly what passed lands on dev.

  1. Give the branch its own required checks: open Settings, pick dev under Branch above Required checks, tick the checks and choose Save. Or from a terminal: ga propose policy --branch dev --require "CI / test".
  2. The agent (or you) proposes for that branch: ga propose --base dev. Agents using the Git A tools pass base to propose the same way.
  3. Follow it as usual: ga propose status, or the proposal's page, which names the branch it lands on.
bash
ga switch -c feature/login        # your own branch
ga commit -am "Fix the login timeout"
ga propose --base dev --wait      # lands on dev once dev's checks pass on it
  • The branch must exist, and the key proposing must be allowed to change it. Otherwise Git A refuses and says why.
  • Without required checks on that branch, a person approves each change, even with Auto when checks pass: nothing lands untested by itself.
  • Once dev requires checks, a direct push to it is refused, and Merge on a pull request into it becomes an approved proposal that lands when the change passes together with the latest dev.
  • Proposals for main work exactly as before: leaving out the branch means the default branch.

7. Work without a local copy

You need the ga tool for this (section 3).

A workspace is your own space on Git A. You change files there and land them, with nothing to download first. Agents connected over the web work this way; you can do the same from a terminal:

  1. Open a workspace: ga ws open --intent "Fix the parser".
  2. Write each changed file into it: ga ws write src/parser.js --from parser.js.
  3. Land it: ga ws land -m "Fix the parser".

Run these inside a copy of the repository, or add -R https://git--a.com/acme/api to each command. Other agents working in their own workspaces at the same time never overwrite your files.

Say which files you plan to change when you open it, for example ga ws open --intent "Fix the parser" --writes src/parser.js. If another agent has already said it will change those files, Git A tells you straight away, before you write anything. Agents get the same answer when they open a workspace over MCP and list the files they will edit. If someone changes one of your files without saying so first, Git A tells you when you write it.

8. Pull requests

Use a pull request when a person should look at a change before it reaches main.

  1. Open the repository and choose Pull requests, then New pull request.
  2. Pick the branch with your change and the branch to merge into (usually main), add a title, and open it.
  3. Reviewers open Files changed, comment on single lines, then Approve or Request changes.
  4. When it is ready, choose how to merge (merge, squash or rebase) and click the merge button. If the change clashes with main, the page shows exactly where.

Agents and scripts can do the same with ga pr create and ga pr merge, the API, or MCP.

9. Issues

  1. Open the repository and choose Issues, then New issue.
  2. Write a title and what needs doing. Add labels, a milestone and assignees: people or agents.
  3. Comment, react and close it when the work is done. When a commit that says “Fixes #12” in its message reaches main, issue 12 closes by itself.

Filters and search work like GitHub’s, so the queries you already use carry over.

Bring issues from GitHub. Move a GitHub repository’s issues to Git A, with their comments, labels, milestones and whether they are open or closed. Each issue says where it came from.

  1. Open the repository’s Issues and click Bring issues from GitHub. You need to be an admin of the repository.
  2. Type the GitHub repository as owner/name, for example octo/web.
  3. Paste a GitHub token that can read its issues, or pick Public repository for a public one. The token is used for this import only and is never stored.
  4. Tick Keep in sync if later changes on GitHub should come over too. For that, connect the repository under Integrations → GitHub first (section 16).
  5. Click Bring issues over and watch the count of issues and comments grow. Running it again later brings what is new and never makes a second copy of an issue.
  6. If GitHub asks to slow down, the import says until when it waits and then goes on by itself. Without a token GitHub allows 60 requests an hour, so a token makes a large repository come over faster.
  7. To stop keeping it in sync, come back to the same page and click Stop keeping in sync. The issues already brought over stay; later changes on GitHub no longer come over.

The same from the command line, inside your clone: put your GitHub token alone in a file and point to it, so the token never shows up in your shell history.

bash
ga issue import github octo/web --token-file ~/github-token.txt --include-closed
ga issue import github octo/web --mirror   # public repository, kept in sync
ga issue import --stop-mirror   # stop keeping it in sync; the issues stay

From the command line. You and your agents can work on issues without opening the website. The commands work like gh issue. Inside your clone they work on that repository. Anywhere else, add the repository’s link, for example -R https://git--a.com/owner/repo.

  1. ga issue list shows the open issues. Narrow it with --label, --assignee, --search or --state closed.
  2. ga issue create opens an issue: give it a --title and a --body. It prints the new issue’s link.
  3. ga issue comment 12 adds a comment to issue 12 (your text goes after --body).
  4. ga issue assign 12 my-agent gives issue 12 to your agent called my-agent. A person is assigned the same way, by their login.
bash
ga issue list --label bug
ga issue create --title "Fix the login page" --body "It fails when the password is empty."
ga issue comment 12 --body "On it."
ga issue assign 12 my-agent

Each command also answers in JSON with --json, using the same field names as gh issue.

10. Actions (CI/CD) and runners

Git A Actions runs your builds, tests and deployments on your own machines, called runners, or on Git A machines that exist for one job only (below). Your code never runs on the servers that keep your repositories. Every CI job, run or skipped, has a small fee. On your own runners that is all Git A charges, never per minute; Git A machines add a price per minute. See Pricing for what Actions costs.

  1. Open your organization, then Settings → Runners, and create a registration key. Name the repositories the machine should serve. Repository admins can add a runner for their own repository: you need to be an admin of each repository you name (you created it, or its creator made you an admin).
  2. You need the ga-runner tool (and ga, if your jobs check out code) on that machine. On a paid plan, download both from Downloads in the app (section 3).
  3. On the machine that should run your jobs, register it and start it:
bash
ga-runner register --url https://git--a.com --token gar_reg_… --name laptop --labels self-hosted,linux,x64
ga-runner run
  1. Add a workflow file to your repository in .gitaworkflows/, for example .gitaworkflows/test.yml. It uses the GitHub Actions format. If a repository has no .gitaworkflows folder, Git A reads .github/workflows/, so your existing files keep working.
  2. Push or land a change. Workflows that run on push start, including when an agent lands a change on main. Watch the live log under Actions in the repository.
.gitaworkflows/test.yml
name: test
on: push
jobs:
  test:
    runs-on: [self-hosted, linux]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

A runner that checks out code needs the ga command on its machine. Safety tip: run ga-runner as its own user account on the machine, or register it with --ephemeral so it handles one job and then signs off. Only let runners that receive secrets run work from branches you trust.

Limits for build files and logs. One job can save up to 20 artifacts, 1 GB in total, and one run up to 100 artifacts, 2 GB in total (each artifact up to 500 MB). Saving an artifact again under the same name replaces it. A job’s log keeps up to 50 MB and a run’s logs up to 250 MB; past that the log says it was cut short. Artifacts and logs count toward your organization’s storage, and give their space back when they expire. Saved dependency folders (Faster checks below) count too.

When CI pauses. If your organization runs out of credits or is suspended, or a repository is archived, its waiting CI jobs are cancelled and running ones are told to stop. Each job’s log says why and what to do. Once that is fixed, push again or run the workflow again and CI picks up as usual.

Follow runs from the command line

You and your agents can see every CI run without opening the website. The commands work like gh run, so an agent that knows GitHub already knows them. Run them inside your clone, or add -R owner/repo anywhere else.

  1. ga run list shows the newest runs. Narrow it with --branch, --workflow (a name such as test or a file such as test.yml), --status (for example failure or in_progress; a word that is not a status is refused and the right ones are listed), --event, --commit (the full commit SHA, or a short one inside your clone), --user and --limit.
  2. ga run view 12 shows run 12: each job and how it ended, and the steps of any job that failed. Add --log-failed to read only the logs of the failed jobs, or --log for every log; --job picks one job.
  3. ga run watch 12 follows a run and prints each job and step as it finishes, then stops when the run is done. With --exit-status it exits with an error when the run failed, so a script can wait on it. If the connection or the server drops for a moment, it keeps following instead of stopping.
  4. ga run rerun 12 --failed runs only the failed jobs again (leave out --failed to run every job). Add --force to run the jobs fresh, even a job that already passed for the same code (for example after your machines changed). It prints the new run’s number to watch. ga run cancel 12 stops a run.
bash
ga run list --branch fix-parser
ga run watch 12 --exit-status
ga run view 12 --log-failed
ga run rerun 12 --failed

Leave out the run number and ga run view and ga run watch use the newest run of your current branch. ga run rerun and ga run cancel always need the number, so they never restart or stop a run you did not mean, such as a deploy or another agent’s checks. Every command also answers in JSON with --json, using the same field names as gh run (for example ga run list --json databaseId,status,conclusion,headBranch).

Faster checks

Four things make your checks finish sooner. Each one is a small change you make once.

1. Run several jobs at once on one machine. A runner takes as many jobs at a time as you ask for. Each job gets its own work folder. Jobs on one machine still share its home folder, so package download caches kept there (such as ~/.npm or pip’s cache) are shared between them. When two jobs must not share a folder, keep it inside the job’s work folder (such as node_modules) or run one job at a time.

bash
ga-runner run --jobs 2

Without --jobs, a runner takes half as many jobs as its machine has processors, and at least one. A machine with 2 processors therefore runs one job at a time until you pass --jobs 2. To keep the number, register with ga-runner register … --jobs 2, or set GITA_RUNNER_JOBS. Jobs of one workflow that do not need each other start side by side. Stop (Ctrl-C, or stopping the service) stops every running job on that machine and reports each one as cancelled.

2. Keep your downloads between runs. Add actions/cache@v4 before the step that installs your packages. The first run saves the folders you name; the next runs get them back without downloading your packages again, and a step can skip the install when nothing changed:

.gitaworkflows/test.yml
steps:
  - uses: actions/checkout@v4
  - id: deps
    uses: actions/cache@v4
    with:
      path: node_modules
      key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-npm-
  - if: steps.deps.outputs.cache-hit != 'true'
    run: npm ci
  - run: npm test
  • key names what you saved. hashFiles(…) turns your lock file into part of the name, so a new lock file saves a fresh copy. When nothing matches the key exactly, restore-keys brings back the newest close match, and the job saves a new copy when it succeeds.
  • steps.<id>.outputs.cache-hit is true only for an exact match. A step’s if:, its run: script and its env: values can read any earlier step’s outputs and results this way (steps.<id>.outcome, .conclusion, .outputs.<name>).
  • A branch can use what main saved, but it never changes it. What a branch saves is used by that branch, by pull requests from it and by pull requests into it; other branches never see it.
  • A restore puts files back only into the folders its step names, whatever the saved copy holds. Keys that start with gita-release- or gita-tools- are saved only by a branch’s own runs: a proposal’s checks cannot save them, and landing a proposal never brings them into your branch. Use them for what your release builds reuse.
  • Each repository keeps up to 10 GB of saved folders. When it is full, what was used least recently goes first, and anything unused for 7 days is removed. Saved folders count toward your organization’s storage. See and delete them with GET or DELETE /api/v1/repos/<owner>/<repo>/actions/caches.
  • actions/cache/restore@v4 and actions/cache/save@v4 do each half on its own, as on GitHub.

3. Use the Python or Node.js already on your machine. actions/setup-python@v5 and actions/setup-node@v4 pick a version that is already installed on the runner and put it first for the next steps. They never download anything, so they take a moment. With cache: pip (Python) or cache: npm, yarn or pnpm (Node.js), they also keep your package downloads between runs.

steps
- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: pip
- run: pip install -r requirements.txt

If the version you ask for is not installed, the step fails and its log lists the versions that are, so you know what to install. To keep several versions side by side, put each in the runner’s toolcache folder (~/.gita-runner/toolcache/Python/3.12.4/x64/ or node/20.11.1/x64/) or set RUNNER_TOOL_CACHE to your own folder of that shape.

4. A full disk stops a job at the start, not half-way. Before each job the runner checks its free disk. With less than 5 GB free, the job stops at once and its log says how much is free and what to do. Change the amount with ga-runner run --min-free-disk-gb 10 (0 turns the check off). ga-runner status shows the free space and the number of jobs at once.

Test only what changed. Tell Git A which files a job reads, and the job runs only when one of them changed. When none of them changed since the job last passed with the same settings, Git A reuses that result instead of running it again: the check still counts, the job shows Reused from run #61 (no inputs changed), and it uses no minutes.

.gitaworkflows/test.yml
jobs:
  web:
    runs-on: git-a
    reuse:
      paths: ['web/**', 'docs/style.md']
    steps:
      - uses: actions/checkout@v4
      - run: cd web && npm ci && npm test
  • reuse: paths: lists the files the job reads. ** matches any number of folders, and a pattern that starts with ! leaves files out.
  • The job runs with only these files in its checkout (and without the repository’s history), so a reused result is always the result running the job again would give. When a step reads a file that is not on the list, Git A runs the job once more with every file, so your check is not held up, and the job’s page and log name the file, for example A step tried to read web/src/x.ts. Add it to reuse.paths. Until you add it, that job is reused only for exactly the same code.
  • A result from someone who cannot write to the repository, such as a pull request from a fork, is reused only for their own later runs, never for yours or for the combined result of a proposal.
  • This works on Git A machines and on your own Linux and macOS runners with the latest ga-runner. On a runner that runs as an administrator (root), on Windows, or with an older ga-runner, a result is reused only for exactly the same code, and the job says so.
  • Without reuse:, a job is reused only for exactly the same code. reuse: false runs it every time, and a job that deploys to an environment always runs.
  • When you start a workflow yourself (Run workflow, or the dispatch API with your own key), every job runs fresh. A run an agent starts reuses results unless it sends "force": true. To run a finished run again with nothing reused, click Re-run all jobs on its page or type ga run rerun 12 --force.
  • Open a job to see why it ran, for example Ran because 2 of its inputs changed since run #60, or that it is the job’s first run. Scripts read the same answer from why in GET /api/v1/repos/<owner>/<repo>/actions/jobs/<id>.

One check for many parts. Split a big job into parts that each list their own files, and add one job with needs: and no steps. That job runs on no machine and uses no minutes: it passes when every part passed (a reused part counts), and it fails, naming the part, when one failed or was skipped. Make it the check that must pass before changes reach main (here CI / test), and a change that touched only the web app waits only for the web part.

.gitaworkflows/ci.yml
name: CI
on: push
jobs:
  server:
    runs-on: git-a
    reuse:
      paths: ['server/**']
    steps:
      - uses: actions/checkout@v4
      - run: cd server && make test
  web:
    runs-on: git-a
    reuse:
      paths: ['web/**']
    steps:
      - uses: actions/checkout@v4
      - run: cd web && npm ci && npm test
  test:
    needs: [server, web]

Keep such a file in .gitaworkflows/: GitHub does not accept a job without steps, so Git A reads this form only there.

Update ga-runner first. A job that uses the cache, the setup actions or a step condition on earlier steps waits for a runner with the latest ga-runner. The Runners page says so when a job is waiting for that.

Checks on Git A machines

No machine of your own to spare? Let Git A run the job. Write runs-on: git-a and each job gets a fresh machine with 4 CPUs and 16 GB of memory (Ubuntu 24.04 Linux, x64). The machine exists only for that one job: nothing from another job or another customer is on it, and it is gone when the job ends. Several jobs run side by side, each on its own machine.

The machine starts with only the basic system and ga, so checking out your code works. Tools such as Node.js, npm or a compiler are not there: add a step that installs what your job needs, like the second step below.

.gitaworkflows/test.yml
name: test
on: push
jobs:
  test:
    runs-on: git-a
    steps:
      - uses: actions/checkout@v4
      - run: sudo apt-get update && sudo apt-get install -y nodejs npm
      - run: npm ci && npm test
  1. Your organization needs prepaid credit: checks on Git A machines are paid from it.
  2. Change runs-on to git-a (or git-a-4cpu, the same machine) and push.
  3. The job shows Waiting for a Git A machine for a moment, then runs. Its live log and result appear under Actions, like any other job.

Price. $0.005 per minute, counted per started minute from the moment your job starts until it ends, plus the same small fee per CI job that every job pays, on your own runners too. Until 30 November 2026 the time the machine takes to start is free. From 1 December 2026 each machine start adds 2 minutes at that machine’s minute price; a check that starts at once on a priority machine, because every standard machine is busy, pays $0.010 a minute (turn on Wait for standard machines in Billing to never pay it); and a check on the Docker-ready image adds $0.07. The Pricing page shows each price with the date it starts. A result Git A reuses because nothing it depends on changed needs no machine: it uses no minutes and pays only the per-job fee. Each job shows up in your billing history as its minutes times the minute price, for example 12 min (10 running + 2 machine start, git-a-4cpu) × $0.005 per minute, with a Docker-ready start as a line of its own, and the minutes per day are on the Usage page (see Read your bill).

When credits run low. A job does not start unless your credits cover about ten minutes. It waits and says so on the run (This check waits for credits). Top up and it starts by itself. A check that is already running stops when your credits are used up and says so on its log (Stopped: your organization’s credits ran out); run it again after you top up. At $0 paid work pauses, clones and downloads too; opening the organization and exporting keep working.

Need Ubuntu 22.04? Write runs-on: [git-a, ubuntu-22.04] and the machine starts with Ubuntu 22.04 instead. runs-on: [git-a, ubuntu-24.04] asks for 24.04 by name. If Git A cannot offer the system you name, the job stops at once and says so: no machine starts and nothing is billed. GET /api/v1/platform/capabilities (no sign-in) lists the systems offered.

The machine runs the job as a normal user that may use sudo, so a step can install what it needs. Next to git-a a job may name one size (git-a-4cpu) and one system (ubuntu-22.04 or ubuntu-24.04); any other label with it is refused: write either git-a or your own runner’s labels.

No fixed limits. Your organization gets as many Git A machines as its checks need, all starting at the same time, and pays only for the minutes they run. When many jobs are queued at once, they start side by side, not one after another. If Git A machines are briefly busy everywhere, a job waits in the queue and starts by itself as soon as a machine is free; it never fails because of a limit.

Your own limits, if you want them. Both are off until you turn them on, in Organization settings → Git A machines (owners and billing managers set them; admins can see them):

  • Machines at once: the most Git A machines your organization runs at the same time, so a burst of agent work cannot run up a large bill in a short time.
  • Monthly spending limit: the most Git A machines may cost in one calendar month (UTC), so a runaway workflow cannot spend more than you planned.

When a limit is reached, new checks wait and say why on the run. They start by themselves when a machine finishes, when the next month begins, or when you raise or turn off the limit. When this month’s cost reaches your monthly spending limit, checks still running on Git A machines stop too and say why; run them again after you raise the limit. The same page shows the price per minute and this month’s minutes and cost, the same amount the monthly limit counts. With a personal token, owners and billing managers can also read and set both limits with GET and PUT /api/v1/orgs/<org>/actions/machine-limits.

Identical checks run once

When two runs need exactly the same check on the same commit, Git A runs it once: the job runs on one machine, and both runs show its live log and its result. Runs started the same way (the same commit pushed again) share with nothing to set up. A push and its pull request share a job when the job says it does the same work for both: add share: events to it. The usual case is a workflow that says on: [push, pull_request]:

yaml
jobs:
  test:
    runs-on: git-a
    share: events            # the same work for a push and its pull request
    steps:
      - uses: actions/checkout@v4
      - run: ./ci.sh
  1. Push your branch and open the pull request as usual.
  2. Open Actions. The job shows running once for #12 and this run in one of the two runs.
  3. When it ends, that job says Same result as run #12 (ran once). A pass passes both runs; a failure fails both.

Minutes are counted once (each job still pays the small per-job fee). Cancel one of the two runs and the job keeps going for the other; cancel both and it stops.

A job runs on its own machine whenever anything it can see differs: another commit or branch, other secrets, or a step in the workflow that uses which event started the run (such as ${{ github.event_name }} or $GITHUB_EVENT_NAME), even with share: events. Only the workflow’s own text counts: leave share: events off a job whose scripts or tools behave differently for a push and a pull request. A job that passed does not run again while nothing it uses changed, also for a run of another event: if a script your workflow calls behaves differently per event, add reuse: false to that job. reuse: false always runs a job on its own machine, and a forced re-run runs every job on its own machine.

When a job cannot start

A job starts on a machine whose labels match its runs-on. When no machine can ever match, the job tells you right away instead of waiting in silence, and it never waits forever.

  1. Open the run under Actions and click the job. A job that cannot start says why, for example No machine can run this: no runner has the labels self-hosted, linux, x64. Use runs-on: git-a for a Git A machine, or register a runner. The run shows the same note at the top.
  2. Workflow copied from GitHub with runs-on: ubuntu-latest? Git A does not provide GitHub’s machines. Change it to runs-on: git-a for a Git A machine (Ubuntu Linux), or register your own runner with that label. For windows-latest or macos-latest, register a runner on a Windows or Mac computer.
  3. Fix it either way. When a runner with the right labels registers, the run says so and the waiting job starts by itself. After changing runs-on, push again or run the workflow again.

The job also says when it waits for a reason that clears by itself: every matching runner is offline or busy, or your runners need the latest ga-runner. If every matching runner is turned off, it says so: turn one back on under Runners. These details about your runners are shown to people who can change the repository or belong to your organization. Anyone else who can read the repository sees only which labels the job waits for.

The 24-hour limit. A job for your own runners that no machine starts within 24 hours stops and fails with the reason it waited, and the rest of its run finishes, just as on GitHub. Fix the cause, then run it again. A job on a Git A machine (runs-on: git-a) is not stopped by this limit: while it waits, for example for credits, the job says why, and it starts by itself once it can. From the command line, ga run view <run> prints waiting: and the reason under each waiting job, and scripts read it as waiting_reason in GET /api/v1/repos/<owner>/<repo>/actions/jobs/<id>.

Check your workflows before you push

Find out what Git A will do with your workflow files before you push them, with no server and no waiting.

  1. In your repository, run ga workflow lint. You can also name files or folders: ga workflow lint .github/workflows/deploy.yml.
  2. The first line tells you which folder Git A reads: .gitaworkflows/, or .github/workflows/ when there is no .gitaworkflows/.
  3. Each file lists what needs your attention, with its line number: an error stops the file from running, a warning is something that will not work the way you may expect, and ignored is a GitHub setting that changes nothing on Git A.
  4. Under each file, -> says what a push will do with it. Fix the errors and run it again. It exits with 1 while any file has an error, so agents and scripts can use it as a check. Add --json for the same answer as data.
ga workflow lint
Git A reads .github/workflows/ (there is no .gitaworkflows/). ...

.github/workflows/deploy.yml
  3:1     ignored  'permissions' in the workflow: has no effect on Git A: ...
  7       warning  jobs.deploy: 'ubuntu-latest' is a GitHub-hosted runner label; ...
  -> Git A runs this file

.github/workflows/test.yml
  12      error    jobs.test: uses actions/setup-java@v4, which Git A does not run yet ...
  -> on push: Skipped: uses actions/setup-java@v4, which Git A does not run yet; ...

2 files: 1 error, 1 warning, 1 ignored

Your GitHub workflows are safe to bring. When Git A reads .github/workflows/, a file it cannot run yet does not fail on every push. Each such file gets one skipped check per commit that says why, it costs nothing, and the rest of your workflows run as usual. GitHub settings that change nothing here are accepted, and the run shows a warning for each one.

What Git A runs today:

  • Starts on: push, landing, pull_request, workflow_dispatch, repository_dispatch, issues, issue_comment, label and milestone, plus github.<event> for a connected GitHub repository. Not yet: schedule, pull_request_target (use pull_request), workflow_run, workflow_call, release.
  • Works as on GitHub: name, run-name, env, defaults, concurrency, and in jobs runs-on, needs, if, env, timeout-minutes, continue-on-error, outputs, defaults, environment (with its url), concurrency and steps. Steps take run, shell, uses, with, name, id, if, env, working-directory, timeout-minutes and continue-on-error.
  • One run at a time: with concurrency: {group: deploy-production} a newer run waits for the running one, and only the newest waiting run is kept. If you land three changes while a deployment runs, you get one more deployment, of the newest change; the runs it replaced show as cancelled with “Replaced by run #N”. The running deployment always finishes, unless the workflow sets cancel-in-progress: true; then the newer run starts as soon as the cancelled one has stopped.
  • Only the deploy waits: put concurrency: deploy-production on the deploy job instead of the whole workflow. Every landing then builds and tests at once, and only the deploy steps take turns, so a landing no longer waits for the previous one’s whole run. A deploy that waits says what it waits for (“Waiting for deploy-production: another job is deploying”), only the newest waiting deploy is kept, and an older change never deploys in place of a newer one that is already waiting, not even when you re-run it. An older change whose deploy is ready only after a newer one has started deploying ends as replaced too, so your environment never goes back to an older change. Jobs and whole workflows that name the same group take turns with each other, and Prod and prod are the same group.
  • Built-in actions: actions/checkout@v4 (ref, path), actions/upload-artifact@v4 and actions/download-artifact@v4 (name, path), actions/cache@v4 with its restore and save forms, actions/setup-python@v5 and actions/setup-node@v4 (see Faster checks above). Other actions, such as actions/setup-java, do not run yet: install the tool on your runner, or with a run: step. For another version of a built-in action (say actions/cache@v3), ga workflow lint names the version that runs.
  • How long artifacts are kept: your plan’s period. Add retention-days: 3 to an upload step to keep that artifact for 3 days only (a whole number, 1 or more; a number larger than your plan’s period keeps it for the plan’s period). When it expires it is removed and no longer counts against your organization’s storage. The step’s log says how long each artifact is kept.
  • Accepted and ignored, with a warning: permissions (a run can only read its own repository), compression-level on uploads (Git A always compresses artifacts), if-no-files-found: error, and fetch-depth, fetch-tags, persist-credentials, clean and token on checkout.
  • Not yet: strategy and matrix, services, container, and reusable workflows.
  • Runners: ubuntu-latest and similar labels are GitHub’s machines. On Git A jobs run on your own runners: write runs-on: [self-hosted, linux]. Every runner has the labels self-hosted, its system (linux, windows or macos) and its chip (x64 or arm64), plus any you add.

Agents can read the same list, with every limit and error code, from GET /api/v1/platform/capabilities. No sign-in is needed.

11. Environments and approvals

An environment is a place you deploy to, such as dev or production. You can make a person approve before anything is deployed there, and every deployment is kept in a history.

  1. Open the repository, then Settings → Environments. Type a name, for example production, and choose Create environment.
  2. Open the environment. Under Protection rules add Required reviewers. If you like, set a wait timer and the branches allowed to deploy, then choose Save rules.
  3. If the deploy needs a password or key, open the repository, then Settings → Actions secrets → Manage. Add a name, for example DEPLOY_KEY, and its value, and save it. The value is never shown again.
  4. In your workflow, give the deploying job environment: production, and use the secret in a step as ${{ secrets.DEPLOY_KEY }} (see the example below).
  5. When the job is ready, it waits. A reviewer opens the run, chooses Review deployments, and approves or rejects it, with an optional comment.
  6. See every deployment, newest first, under Deployments in the repository.
.gitaworkflows/deploy.yml
name: deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: [self-hosted, linux]
    environment: production
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

Secrets reach only workflows from main, unless you add more branches under Trusted refs on the same page. A pull request from an agent branch never gets them: there every secret is empty, and the run says so.

Git A hides secrets in a job’s log: where a step prints one, you see *** instead. To hide a value your job only gets while it runs, such as a token it fetches, print ::add-mask:: followed by the value, for example echo "::add-mask::$TOKEN". From that line on, the value shows as *** in the rest of the job, also in common encoded forms such as base64 on one line. Register a value in an earlier step than the one that prints it. Values shorter than 3 characters are not hidden, and a value printed in some other form can still show, so never print a secret on purpose.

Every job also gets its own key, as on GitHub: ${{ secrets.GITHUB_TOKEN }}, or ${{ github.token }}. It only reads this repository (it cannot change issues or comments), works until the job ends and shows as *** in the log. To use ga in a step, give the step GITA_TOKEN: ${{ secrets.GITHUB_TOKEN }} under env:. When someone who cannot write to the repository opens or comments on an issue, the run gets this key but none of your other secrets. A run from an untrusted branch gets no key at all, and its log says why.

12. See your agents live

  1. Open a repository and choose Live to see which agents are working in it right now.
  2. The repository’s Home page shows Activity: pushes, branches, changes landed on main, pull requests, workflow runs, deployments and issues, newest first. New items appear as they happen, without a reload.
  3. Open an agent under Agents to see its own history.

13. Never lose an agent's work

You need the ga tool for this (section 3).

An agent's work in progress lives on one computer until it is committed and pushed. If that computer stops, the agent's session ends or its AI credits run out, the work could be lost. Git A keeps a copy of it for you: every few seconds, the agent's unsaved changes (edited, new and deleted files, and commits not pushed yet) are saved to Git A.

  1. In the agent's copy of the repository, run ga mirror start. You will see Saving this working copy to the server every few seconds. It keeps running in the background.
  2. Agents working on their own branch (agent/…) on Git A start saving by themselves after their first ga command. To turn that off for a copy, run ga mirror stop; to turn it on for any branch, run ga config mirror.auto true.
  3. Check it at any time with ga mirror status: when it last saved, what changed, and any file it did not save. ga mirror stop saves one last time and stops.
  4. Open the repository and choose Live: each agent's lane shows saved unsaved work as it happens. When two agents change the same files, you see it there right away, before anything is put on main.

What is not saved, so nothing private or huge is copied:

  • files your .gitaignore leaves out;
  • new files that look like secrets, such as .env, *.pem, *.key, id_rsa or .npmrc (add more with ga config mirror.exclude "*.secret");
  • files over 25 MB, and binary files over 2 MB.

ga mirror status lists each file it left out and why. Only people in your organization who can read the repository can see saved work. It counts toward your organization's storage, and old saved copies are cleaned up by themselves. Saving never changes main and never publishes anything: when the work is ready, the agent still proposes it (section 6).

When you change the task

Sometimes you stop an agent half way because you want something else done. You decide what happens to the work it had started.

  1. To keep it for later, run ga park in the agent's folder. Git A saves the work one last time and sets it aside. You will see Parked lane agent/x. It is kept for 30 days.
  2. The folder stays as it is. Add --clean (ga park --clean) to also put the folder back to its last commit, ready for the new task. This only happens after the work is safely saved. If a changed file could not be saved (a very large file, for example), Git A names it and leaves the folder as it is, so nothing is lost.
  3. Parked work is listed under Parked work you can pick up in ga recap and ga mirror status. To carry on with it, run ga resume agent/x --into agent-x (section 14).
  4. To throw the work away instead, run ga discard. It asks you first (agents add --yes), then deletes the saved copies and undoes the unsaved changes in the folder. If the agent made commits that are not on main, pushed or proposed yet, ga discard stops and lists them: propose them, park the work, or add --force if you really want them gone.

Parking and discarding never change main, branches on Git A, proposals or anything already put on main. Agents connected over MCP use the park and discard tools, and the agent guide tells them to park when you change the task.

14. Pick up where an agent stopped

You need the ga tool for this (section 3).

When an agent stops, another agent (or you) can carry on exactly where it left off, on the same computer or a different one.

  1. Run ga resume agent/x --into agent-x (use the agent's branch name). Git A brings back its last saved work into the new folder agent-x: the same files, the same staged changes and the commits it had not pushed. You will see Restored lane agent/x, followed by a short summary.
  2. This computer now holds the lane and keeps saving it. Add --peek to only look at the work and leave the lane where it is.
  3. Run ga recap whenever an agent starts or comes back. In a few lines it shows what changed while it was away (changes on main to the same files, check results, reviews and approvals of its proposal, other agents on the same files), what it had finished, where it stopped, and the next step. Add --json for a program, or --since 2h to look further back. Agents connected over MCP use the recap tool.
  4. Before stopping, an agent can leave a note for whoever picks the lane up: ga recap --note "parser half done, tests in parser_test.rs fail". Only the working copy that holds the lane can write its note. Notes from other agents are shown apart, as quoted text, and are never treated as instructions.

If the first computer comes back later, its newer local work is never lost and never overwrites the lane: Git A keeps it as a separate copy, and ga mirror status on that computer tells you so and how to open it, for example ga resume agent/x --aside 1 --into old-copy.

Running ga resume agent/x without --into restores into the folder you are in. If that folder has edits or commits the server never saved, nothing is touched: you will see local disk wins, and you resume into a new folder with --into instead. A dropped connection or a server restart while an agent is being saved loses nothing either: the next save carries on by itself.

Wait for changes

Your agent can wait until someone changes a file it depends on, instead of checking again and again. The moment such a change lands on main, the wait ends and lists the files that changed. Nothing is missed between two waits. It is included on every plan and uses no CI minutes or storage. Changes by your other agents wake it too, even when they share one account; only your own version of a file arriving does not.

Agents (MCP):

  1. Your agent calls the wait_for_change tool. In a clone it needs no settings: it watches the files its branch changed and the files it is editing.
  2. To watch something else, give it path patterns such as src/billing/**, a branch, or your proposal number.
  3. When it answers, your agent brings those files up to date and calls it again with since from the answer. If nothing changed before the time ran out, it calls again the same way.

In a terminal:

  1. Run ga wait in your clone.
  2. It returns as soon as main changes a file you are working on, and lists those files, for example M src/billing/invoice.rs.
  3. Add --paths 'src/billing/**' to watch other files, --timeout 30m to wait longer, or --json for scripts. Exit code 0 means something changed, 2 means nothing changed before the timeout.

15. API and live events

Every path starts with /api/v1 and takes your key in the header Authorization: Bearer gat_…. A script can create an agent and its key without a browser. First make your own key for it:

  1. Open Your settings → Personal access tokens → New token.
  2. Pick the repositories, tick agents:write (to create agents) or hooks:write (to connect GitHub, section 16), choose a lifetime and create it.
  3. Copy the key (it is shown only once) and run export GITA_PAT=gat_…. Then:
bash
curl -X POST https://git--a.com/api/v1/orgs/acme/agents \
  -H "Authorization: Bearer $GITA_PAT" -H "Content-Type: application/json" \
  -d '{"name":"fixer-1","grants":{"repos":["acme/api"],"refs":["refs/heads/agent/fixer-1/*"],"land":true}}'

curl -X POST https://git--a.com/api/v1/orgs/acme/agents/fixer-1/tokens \
  -H "Authorization: Bearer $GITA_PAT" -H "Content-Type: application/json" \
  -d '{"ttl_s":3600}'

refs lets the agent push only to branches that start with agent/fixer-1/; ttl_s 3600 makes the key stop working after one hour.

To watch what happens in your organization live, open the event stream. You only see what your key may read. If the connection drops, reconnect with the last event ID you received (Last-Event-ID) and you pick up where you left off.

bash
curl -N "https://git--a.com/api/v1/orgs/acme/events/stream?types=landing,issues,label" \
  -H "Authorization: Bearer $GITA_TOKEN"

Every answer carries x-gita-elapsed-us: how long the server took, in microseconds.

API reference

The endpoints for accounts, organizations, agents, issues, Actions, environments, webhooks, events and billing. Pull requests, landing, workspaces and MCP are covered in the steps above.

16. Webhooks

Webhooks tell your other tools what happened. They fire on pushes, changes landed on main, pull requests and reviews, Actions runs, and every issue, label, comment, milestone and reaction change.

  1. Open the repository (or your organization), then Settings → Webhooks, and add one with your URL and a secret.
  2. Choose the format: Git A, GitHub-compatible (existing GitHub receivers work unchanged), or a ready-made message for Slack, Discord or Microsoft Teams.
  3. Pick the events you want and save. Every delivery is listed in its delivery log, where you can send it again.

Using Slack, Discord or Teams? You are done after step 3. The rest is only for your own programs that receive webhooks.

Each delivery carries X-GitA-Hook-Seq, a number that goes up by one for every delivery of that webhook: if a number is missing, a delivery was missed, and you can send it again from the delivery log.

To check that a delivery really came from Git A, verify X-GitA-Signature-V2: t=…,v1=… (HMAC-SHA256 of "<t>." + raw body with your secret) and reject timestamps more than 300 seconds old. X-GitA-Signature-256 and, in the GitHub format, X-Hub-Signature-256 carry the signature of the body alone.

verify signatures · node
import crypto from "node:crypto";

export function verify(secret, rawBody, header, nowS = Math.floor(Date.now() / 1000)) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? "");
  if (!m || Math.abs(nowS - Number(m[1])) > 300) return false;
  const mac = crypto.createHmac("sha256", secret).update(m[1] + "." + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(m[2]));
}
// verify(process.env.HOOK_SECRET, body, req.headers["x-gita-signature-v2"])

Keep using GitHub alongside Git A

Keep working on GitHub while your agents work on Git A: events from GitHub show up in Git A and can fire your Git A webhooks and start your Git A Actions workflows.

  1. In your organization open Integrations → GitHub.
  2. Connect one GitHub repository, or a whole GitHub organization (each of its repositories maps to a Git A repository).
  3. Git A shows a webhook URL and a secret once. Copy both.
  4. On GitHub, add a webhook with that URL, content type application/json, the secret, and the events you want. GitHub’s first test message marks the connection as verified.

A script can make the same connection. It needs your own key with hooks:write ticked (section 15).

API
curl -X POST https://git--a.com/api/v1/orgs/acme/integrations/github \
  -H "Authorization: Bearer $GITA_PAT" -H "Content-Type: application/json" \
  -d '{"kind":"repo","github_repo":"octo/web","repo":"web","events":["*"]}'

17. How we measure speed

Every speed number on this site comes from our head-to-head tests against GitHub.com on 1 and 2 November 2026. These are their conditions:

  • The same scripted agent work ran back to back on GitHub.com and on Git A v0.4.0, hosted in Mumbai, India.
  • Both were run from one laptop on a home internet connection in Kolkata, at about the same network distance: 67 ms to GitHub and 59 ms to Git A.
  • The project was Express.js with its full history (6,183 commits), with the same commit IDs on both sides.
  • Many agents at once (2 Nov 2026): the middle result (median) of 5 runs for each size and situation, GitHub and Git A taking turns going first. Every run was checked on both servers: each agent’s change was on main exactly once.
  • One agent (1 Nov 2026): a single change is the median of 10 runs and a fresh copy (clone) the median of 3; the other one-agent tests ran once on each side.
  • CI time is not included. One repository, one location; your numbers will differ.

For example, 10 agents changing different files at the same moment took 27.17 s on GitHub, with 45 rejected pushes, and 0.69 s on Git A, with no retries. Every number, with what each test does, is on the full results page, and the short version is on the home page.

18. Limits and fair use

Git A keeps every organization fast when the server is busy. These are the limits you can meet, and what to do.

  • Files are at most 1 GB. A push or an import with a bigger file is refused with 413; a file edited through a server workspace is at most 100 MB. Keep anything bigger in run artifacts or releases. A repository moved from GitHub, GitLab or your own Git server with a bigger file anywhere in its history needs that file removed from history first.
  • One push or upload is at most 4 GB. A bigger one is refused with 413. Push a large history in a few smaller pushes, a few commits at a time.
  • Storage per organization. Organizations pay for what they store, up to 50 GB per organization; ask support to raise it. Storage counts what your repositories keep, including work saved in server workspaces, and your CI run artifacts and logs. Owners and billing managers get a warning at 80 % and at 95 % of the limit, by email, as a banner in the app and on the Billing page. When an organization’s storage is full, changes answer 402 with what is left, who can make room and a link to Billing, and nothing past the limit is kept. CI jobs still save up to the last 64 KB of their logs when they end, where a failed run says why, and the run says that its logs were cut short. Run artifacts and logs free their space when they expire. Reads, clones and downloads keep working.
  • Busy answers. When many requests from the same account run at once, extra ones wait a moment and may get 429 with a Retry-After time. ga waits and tries again by itself; your own scripts should wait the number of seconds in Retry-After, then retry.
  • Slow connections. A request that sends its data very slowly (under about 1 KB a second for 20 seconds) is stopped, so it cannot hold a place in line. Normal connections, even slow mobile ones, never come near this.
  • Live event streams reconnect about once an hour. Event clients reconnect on their own and pick up from the last event they saw.
  • All limits as data. GET /api/v1/platform/capabilities (no sign-in) lists the limits above, CI limits, each plan’s caps, what workflows may contain and every error code with what to do.
  • Short of storage. In the rare case the server is low on space, changes answer 507 for a few minutes. Reads, clones and fetches keep working.

19. Credits and your agents

On a paid plan your organization runs on prepaid credits. Your agents learn how the credits stand on every answer, long before anything stops, so a run never fails by surprise.

The four states you can see:

  • ok: enough credits. Nothing to do.
  • low: under a quarter of your last top-up, or under $2. Everything still works. Top up soon.
  • empty: no credits left. Your agents' downloads pause (every person in the organization can still export their code each day), and the next charged usage makes the organization read-only. Top up now.
  • read_only: the credits are used up or cover less than one month of your storage, so your stored data always stays paid for. Pushes, landings, new CI jobs and other changes stop and answer 402 with a link to Billing. Top up and they work again at once.

Your code is never locked away. While you have credits, even when your organization is read-only, you and your agents can still read files, clone, fetch and export every repository, with every commit. You are never charged for usage you did not pay for: once the credits are used up, downloads pause until you top up, and every person in the organization can still export their code each day.

Where your agents see it:

  1. The ga command line prints one line when credits are low, empty or read-only, for example:
    warning: Credits are running low ($1.50 left). Top up so your agents keep pushing, landing and running CI: …
    It goes to the error output, so your scripts and --json output are not changed. To turn it off, set GITA_NO_BALANCE_WARNING=1.
  2. MCP tools add the same warning as a separate note after the tool’s result, so your agent reads it and the result itself is unchanged.
  3. Every API answer about your organization, sent to one of its members, carries the state in the x-gita-balance-state header (ok, low, empty, read_only) and, when there is something to do, what to do in x-gita-balance-hint. People outside your organization never see it.
  4. CI: a job that starts while credits are low says so on the first line of its log. A job is never started once the organization is read-only, and its check says why in plain words.

Check before expensive work. Any member of the organization, and any of its agents, can ask:

bash
curl -s -H "Authorization: Bearer $GITA_TOKEN" https://git--a.com/api/v1/orgs/acme/billing/state
# {"org":"acme","state":"low","balance_usd":"1.50","hint":"Credits are running low ($1.50 left). ...",
#  "writes_allowed":true,"reads_allowed":true,"billing_url":"https://git--a.com/app/orgs/acme/settings/billing"}

If writes_allowed is false, do not start a long job yet. When state is read_only, ask an owner or billing manager to top up in Settings → Billing. Otherwise the organization is on hold: its creator has not verified their email yet, or it is suspended (the organization's page says which; for a suspension, contact the Git A team).

See what you used and what is left. Open Settings → Billing. The first screen shows your plan, the credits left, what this month cost so far and about how long the rest lasts at this month's pace (an estimate). Below it, every part of the month (minutes on Git A machines, storage, pushes and merges, CI jobs, downloads) with what was used and what it cost, and the limits that apply right now, such as how many Git A machines can run at the same time, with how much of each is in use. Owners, admins and billing managers see it.

Set a monthly budget. On the same screen, slide the Monthly budget (or type an amount; in India it is in rupees). While you slide you see what this month will cost at today's pace (an estimate), how much of the budget is used and how much is left, the day it would be reached, and about how many Git A machine minutes it buys. Tick Spread it over the month so the budget is not used up early: work waits once the day's share is used, and what you did not use rolls over to the next days. Click Save budget.

At the budget, new checks on Git A machines wait and say Monthly budget of ₹8,000 reached. Raise it in Billing to continue. on the job, the proposal and in ga (people outside your organization see only that the check waits, never the amount). They start by themselves next month, or at once when you raise the budget. Checks still running on Git A machines when the month reaches the budget stop and say why; run them again after you raise it. Nothing is lost or locked: storage, saving, pushes and reads keep working. You get an email at 75% and at 100%. The month and its days run in UTC (the day's share begins at 05:30 in India). Owners and billing managers change the budget; everyone else in the organization sees it read-only. In a terminal: ga billing budget shows it, ga billing budget set 8000 sets it and ga billing budget set off removes it (0 is not accepted, so a typo never removes your limit).

Deploys go first. When Git A machines are busy or the budget is tight, the checks of a deploy start before everything else, then the checks that land a proposal, then proposal checks, then other branch checks (oldest first in each). With a budget, branch and proposal checks also leave room for your next deploys: about two deploys a day, at what your last deploys cost. The budget card shows it in plain words, for example ₹480 kept for deploys. A branch check that would use that room waits and says how much of the budget is left, what of it is held back and for what (kept for deploys, counted for the checks running now), and what the check needs, for example Waiting: ₹600 of the monthly budget of ₹8,000 is left, and ₹480 is kept for deploys and ₹110 is counted for the checks running now, so only ₹10 is free for this branch check (it needs about ₹19). The budget card shows what is free for branch and proposal checks now. A branch check still running when only the room for deploys is left of the month's budget stops (run it again later). Deploys may use the room, and landing checks all of it but one deploy's worth, so the deploy a landing leads to still starts; the budget itself is never passed, so at the budget deploys wait too. Only runs of your default branch whose workflow deploys to an environment count as deploys. Owners and billing managers can turn this off or change how many deploys a day it keeps room for, under Deploys first on the same card. Without a budget, only the order applies.

See what everything costs

Every check, run, proposal and deploy shows what it cost, right where you already look. No separate report to open, and every figure is what you are charged.

  1. A run or a job: open it under Actions. Next to its name you see, for example, cost $0.06 · 12 min. A job also says its machine and price: $0.06 for 12 machine minutes on 4 CPU, 16 GB at $0.005 a minute, charged.
  2. A proposal: its page has a Cost line with the total, its own checks and the checks it ran together with the latest main.
  3. This month: the organization's page shows the month in one line (checks, storage, data transfer and extra people). The Agents and Members lists show what each agent and each person used, the repository page shows the repository's month, and Deployments shows each deploy.
  4. From the command line: ga run view 42 prints a cost: line for the run and each job, ga run ls has a COST column, and ga pr view 12 prints the proposal's cost. Add --json and each answer has a cost field.
  5. For agents: the MCP tools ci_run and proposal_status include cost too, so an agent knows what its checks cost.

What the words mean: charged is taken from your credits. so far (still running) grows until the job ends. reused, no charge: an identical check had already passed, so nothing ran. your own runner, no charge: it ran on your machine. A machine that was replaced during a job is never charged; the job simply runs again.

Owners, admins and billing managers see the whole organization. Other members and your agents see the repositories they can open.

Read your bill

Every charge on your bill is a quantity times a price, so you can check each line yourself. Owners, admins and billing managers see the overview and the ledger; invoices and top-ups are for owners and billing managers.

  1. Open Settings → Billing. At the top you see Credits left, Used this month and Lasts at this pace: about how many days your credits last if the rest of the month goes like the days so far (an estimate).
  2. Under What you used this month, each line shows what you used, its price and what it cost, for example 30 minutes × $0.005 per minute = $0.15. The lines are: checks on Git A machines (minutes); from 1 December 2026 also the minutes at the priority price, machine starts and Docker-ready starts; storage (GB-months); downloads by people and agents (GB); downloads and uploads by your CI machines (GB); the build cache (GB-months); cache and file writes and reads, pushes and merges, and CI jobs (each per 1,000); and extra people (per person a month). A line that is counted but not charged says so.
  3. Open Ledger to see each charge when it was taken, with its quantity and price. Charges that grow during the month, such as storage, show the month so far, for example This month so far: 2 GB-month × $0.50 per GB-month; the amount next to it is what that hour added.
  4. Open Invoices (owners and billing managers). Each invoice line shows its quantity and unit price, then the GST. You pay the price of your credits and any GST, and nothing for the way you pay: for example, $25.00 of credit costs $25.00 plus any GST.
  5. Your plan line says what the monthly price buys. When a price list keeps a platform fee, it reads, for example, $10.00 a month: $7.00 in credits + $3.00 platform fee.

Alerts. You get an email when your credits fall to 25 %, 10 % and 0 % of your last top-up.

At $0. Paid work pauses: pushes, merges, CI runs, clones and downloads, and other changes wait until you add credits. Your code stays readable: you can still open it in Git A and each member can export it.

Never pay the priority price. On the Billing overview, turn on Wait for standard machines. When every standard machine is busy, your checks then wait for one instead of starting at once at the priority price.

20. Change the default branch

The default branch is the one new proposals, checks and deployments use, and the one a fresh copy of the repository starts on. When you create a repository, the New repository window has a Default branch box, already set to main; change it there if you want another. An agent’s own branches never become it.

  1. Open the repository, then Settings. Under General, find Default branch.
  2. Pick a branch from the list and choose Update. The dialog says what moves with it; confirm.
  3. New proposals, checks and deployments use it at once, and the checks you require before landing move with it. Open proposals that targeted the old branch stay as they are; the message tells you how many there are.

From the command line:

bash
ga repo edit acme/api --default-branch main

The repository’s creator and people with the admin role on it can change it. The branch must already exist. A repository with nothing in it yet shows a box instead of a list: type the name of the branch it should wait for. If changes are still landing, wait a moment and try again.

21. Delete a repository

Deleting a repository removes its code, checks, issues and proposals, and frees its name at once, so you can create a new, empty repository with the same name straight away.

  1. Open the repository, then Settings, and scroll to Danger zone.
  2. Choose Delete repository. You see what will be removed.
  3. Type the repository’s full name, for example acme/api, and choose Delete repository. If you signed in a while ago, Git A asks for your password first.
  4. The repository disappears right away, its running checks stop, and you get an email saying it was deleted.

From the command line (it asks you to type the name; scripts pass it with --confirm):

bash
ga repo delete acme/api
ga repo delete acme/api --confirm acme/api
ga repo create acme/api --private --default-branch main   # the same name, new and empty

A personal access token can delete only when it was created with the repos:delete permission (Settings → Tokens). Agents can never delete a repository.

Only the person who created a repository can delete it. Organization owners and admins cannot, and neither can people added to it. Agents and tokens that were allowed to use the name keep those rules: they work with a new repository of the same name, which starts with no history, no people, no webhooks and no secrets of the old one.

Deleted one by mistake? Contact support within 7 days and we can bring it back.

22. Use plain git with Git A

You can keep using the git you already have. Clone, pull and push work with Git A without installing anything new, and every commit keeps exactly the same ID.

  1. Make a key: Your settings → Personal access tokens → New token. Pick the repositories and tick Write if you will push. Copy the key (it starts with gat_ and is shown only once). An agent uses its own key (section 5).
  2. Clone with the address of your repository. When git asks for a user name, type anything (your login is fine). When it asks for a password, paste the key.
  3. So git does not ask every time, let it remember the key. Most installs of git offer a password manager; the line below saves the key in a file in your home folder instead.
bash
git clone https://git--a.com/acme/api.git          # user name: anything, password: your gat_ key
git config --global credential.helper store    # optional: remember the key

An existing project on your computer: add Git A as a second place to push to.

bash
git remote add gita https://git--a.com/acme/api.git
git push gita main
git pull gita main

Branches, tags and deleting a branch work as you expect, and so does --force on your own branches. For build machines, git clone --depth 1 fetches only the latest version, and --filter=blob:none fetches files only when they are needed.

The same rules apply as with ga: agents push their own branch and propose it, they never push straight to main (section 6), and nobody can delete main. Pushes use the same storage and have the same size limits as with ga (section 18), except that one file pushed with git is at most 512 MB, and one git push carries at most about 4.8 million objects (every version of every file and folder, and every commit): push a very large history in parts, an older commit first. When a push is refused, git prints the reason and what to do in plain words next to the branch name.