Team workflow

-  o1: { id: "o1", status: "paid", total: 4800, items: [ … ] },
+  o1: { id: "o1", status: "paid", totalCents: 4800, currency: "USD", items: [ … ] },

✓ POST /auth/login       200 OK
✓ GET  /products         200 OK
✓ GET  /orders/o1        200 OK  totalCents exists
Evidence recorded: Tests passed 3/3

$ git add backend getman
$ git commit -m "Order totals in cents (GT-SHOP-001)"
$ git push
To origin  main -> main

→ list_changes { consumer: "web" }
  GT-SHOP-001  potentially-breaking  Tests passed
→ get_change { id: "GT-SHOP-001" }
  diff, examples, migration, evidence

 * @typedef {{ id, status,
-   total: number, items }} Order
+   totalCents: number, currency: string, items }} Order
-  return `$${(order.total / 100).toFixed(2)}`;
+  return `$${(order.totalCents / 100).toFixed(2)} ${order.currency}`;

This page follows one API change from the backend developer, Alice, to the web developer, Bob. Both of them work in their own clone of the same repository, and Git carries the change between them. No handoff document is needed.

Before you start

• Git, Getman, and Node.js 20+ for the command line.
• A repository that contains a getman/ folder. See getting started if you need to set one up.
• Your consumer name. The web developer uses web, and the backend developer uses the name the team agreed on.

Open the team workspace from a fresh clone

Clone the repository, then open the getman folder in Getman.

1. Clone the repository as usual.
2. In Getman, choose Open a team workspace on the Welcome screen. You can also use Open team workspace… from the title bar menu or the command palette (⌘K).
3. Pick the getman folder inside your clone. It is the folder that contains getman.yaml.
4. Open Environments and type the secret values once. They are masked, stored in your system keychain, and never written to Git.

To link a project you created yourself, open Project settings, go to Team sync, and choose Choose folder. Pick a folder inside your repository.

The backend change (Alice)

1. Change the API. Then update the matching Getman requests in the app, or let your agent edit the request files. Update examples, assertions and any new endpoints.

2. Create the change package. Use New change package in the Changes view, the palette item New change package…, or the command:

   getman change new --workspace getman --title "Order totals in cents, with currency" \
     --summary "GET /orders/{id} returns totalCents and currency." \
     --migration "Read totalCents (integer cents) and currency. total is gone." \
     --author "Alice (backend)"

   The command prints the reference, such as GT-SHOP-001.

3. Verify against a running API. Use Verify now in the change, or run getman change verify GT-SHOP-001 --workspace getman --env Local. Failing runs are recorded as evidence too.

4. Publish the change when it is final. Use Publish in the change’s header, or run getman change state GT-SHOP-001 published --workspace getman.

5. Commit the code and the getman/ files together, then push.

The web change (Bob)

1. Click Fetch in the Git bar. The new package appears in the Inbox as Not pulled.

2. Click Pull. Getman asks before a pull replaces requests you have changed.

3. Read the package: the diff, the examples, the migration notes and the evidence. From a terminal, run getman change show GT-SHOP-001 --workspace getman.

4. Update the web client and run its tests.

5. Report the status. Use Report status in the change, or run:

   getman change report GT-SHOP-001 --workspace getman --consumer web --status verified --author "Bob (web)"

   verified is accepted only after a passing run against the current contract. Run Verify now first if you have not already.

6. Commit and push.

After Bob pushes, and Alice clicks Fetch and Pull, the change shows Integration verified in her view.

Find the change you need

The Changes view has four views: Inbox, Completed, All changes and Timeline. Set I integrate as to your consumer name, so that the Inbox shows the changes still waiting for your team.

The Completed view lists the changes your consumer has already finished.

Git actions are explicit

Getman reads the folder and the fetched branch, and it flags incoming packages and request edits. It does not change Git on its own.

Action	What it does
Fetch	Runs git fetch.
Pull	Runs git pull --ff-only. It never merges.
Commit…	Commits only the Getman files you tick.
Push	Pushes the current branch. It never forces.

Merges and conflict resolution happen in Git, as usual. If a pull is refused because of local changes, commit or discard them first.

Common questions

• Two people created GT-SHOP-007. Give one of them the next free number, rename the file to match, and commit. See troubleshooting.
• Bob’s tests fail after Pull. That is expected for a breaking change. Update the client, then verify again.
• Alice cannot see Bob’s status. She needs to Fetch and Pull after Bob pushes.

For the file format and the verification rules, see change packages. To let a coding agent do these steps, see connecting a coding agent.