> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following https://api.getcargo.io/INSTALL.md` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://raw.githubusercontent.com/getcargohq/cargo-skills/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits, valid for its first 30 days, and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# GitHub

> Connect a repository to a project: Cargo plans every pull request and deploys the production branch when it merges, with no workflow file of your own.

Connect a repository to a project and Cargo runs it for you. Every pull request
gets a plan — a comment showing exactly which live resources the branch would
change, and a check that fails when the project does not compile. Every push to
the production branch deploys.

There is no workflow file to write and no API token to store in GitHub. Cargo
clones the commit itself, runs your project's own `@cargo-ai/cdk`, and reports
what it found.

## Connect a repository

**1. Install the Cargo GitHub app from Cargo**

**Settings → States**, open the project's state, and choose **Install
Cargo HQ**. GitHub asks you to authorize Cargo, then to pick the
repositories. Coming back links that installation to your workspace: it is
what shows Cargo the workspace may connect those repositories, and what
stops another workspace from claiming them. Only an owner of the GitHub
organization (or the GitHub user) the app is installed on can link it. An
installation that already exists is linked the same way, from its
settings page.

**2. Connect it to the project**

In the same place, name the repository, the branch that deploys and the
directory that holds `cargo.json` and `cargo.state.json`. Connecting is
refused unless the app is installed on the repository through an
installation linked to the workspace. `cargo-ai project state connect`
does the same from a terminal, and opens the install link when the
installation is not linked yet.

**3. Open a pull request**

Cargo comments the plan on it, and updates that same comment on every later
commit.

A repository can hold more than one project: connect each directory separately,
and each gets its own check and comment. A pull request runs only the projects
whose directory it changed, plus every project when the root `package.json`,
`package-lock.json` or `cargo.state.json` changed. A push deploys a project when
its directory changed since the commit that project last deployed, so a change
whose deploy failed or was paused goes out with the next push. Code a project imports from outside its directory
does not count, so keep a project's code inside it.

## What a pull request does

**Nothing.** A plan is read-only — it compiles the branch and diffs it against
the deploy state your workspace already holds. It creates no resources, writes
no state, and needs no credentials: Cargo hands the sandbox a copy of the state
and nothing else.

The comment lists the resources that change and counts the ones that do not:

```
0 to create, 2 to update · 331 unchanged
```

Resources tracked in state but no longer in code are shown as **Prune**. A
deploy leaves those in place — removing them stays a deliberate
`cargo-ai project deploy --prune`, run by you.

The check fails only when the project does not compile: an unknown reference, a
cycle, a file that will not import. A large diff is not a failure.

## What a merge will set in motion

Above the resource table, the comment says what merging starts, in one table:
every play the pull request creates or updates and leaves enabled, and every
execution it runs once. Each row counts the records it runs on and what its
steps send for them.

| What | Runs | Records | Sends, at most | Credits, at most |
| - | - | - | - | - |
| Expansion | play, keeps running | 1,200 | 1,200 emails, 1,200 chat messages | 1,200 |
| `2026-10-14-pilot` | batch of Expansion, once | 40 | 40 emails | 40 |

A new play, or one this change enables, enrolls every record its filter
matches. A play that is already running, with its filter unchanged, counts only
the records that match it now and it does not hold yet, so changing a step's
wording does not read as a fresh send. One whose filter, sort or limit changes
counts every record it matches: a new filter can swap who the play holds for as
many others. A play keeps enrolling records that match it after the merge, so
its row is a snapshot.

An [execution](https://docs.getcargo.ai/deploy/executions.md) the merge would run is a row of its own. It
runs once, so its row is all of what it does: the records a filter matches now
under its limit, a segment's records, the ids it lists or the form records it writes, a file's
rows, or one for a run.

Counts assume every branch is taken. Actions on a connector that uses your own
API key cost no credits. Emails, LinkedIn actions, Slack and Teams messages, and
audience adds are counted, including steps inside a loop, once per record.
Steps that call a tool or an agent are noted but not counted. Plays and
executions add up to one total for the approval limits. Each execution's notes
also say how many records the merge may find: for a filter or a segment, up to
10% over the count, and at least one more, for records that arrive in between.

### Approving a large merge

When a pull request would send more than 100 emails, LinkedIn actions or chat
messages, add more than 5,000 records to an audience, or spend more than 2,500
credits, its check stops with **Action required** and the title **Needs
approval: add the cargo:approve-impact label**, and the comment opens with the
same ask. Nothing is broken: the check holds the merge the way a failure would. It is
also held when a play or execution that sends or spends credits cannot be
counted: its model or segment is created by the same change, its steps could
not be read, or it sends inside a loop, which runs an unknown number of times
per record. Add the
`cargo:approve-impact` label to the pull request and Cargo plans it again, this
time passing. Removing the label holds it again.

Make the Cargo check required in your branch protection for this to stop the
merge. It is named **Cargo**, or **Cargo (`directory`)** for a project that is
not at the repository root.

## What a merge does

A push to the production branch runs `cargo-ai project deploy --yes` on that
commit, against the workspace the state belongs to. Deploys of one project run
one at a time in the order they landed, and when several are waiting only the
newest applies, since it contains the others. A commit older than the one
already deployed is never applied. A deploy also takes the same lock the CLI
does, so it cannot overlap a teammate's local deploy.

A deploy runs as a **service user**, never as a person, with a credential Cargo
mints for that run and revokes when it ends. Unless you pick one when
connecting, Cargo creates a service user for the repository with your
permissions; you can change it to any service user whose permissions you hold.
Anyone who can push to the production branch can change what that service user
can change, so give it only what the project deploys, and protect the branch the
way you would protect production.

A merge only starts the [executions](https://docs.getcargo.ai/deploy/executions.md) a pull request
previewed. Before starting one, the deploy checks three things:

* A successful plan counted this exact version of it.
* That plan was approved: it was under the limits, or it carried the
  `cargo:approve-impact` label.
* It runs on no more records now than that preview allows.

An execution that fails a check is **held**. It does not start and stays
pending, and the deploy's check names it with the reason. The next pull request
previews it again, and a merge after that runs it. An execution pushed straight
to the production branch is held the same way. To run a held execution with
`cargo-ai project deploy` from your machine, turn **Deploy on push** off first:
while it is on, only the connection's service user can deploy this state.

Turn **Deploy on push** off to keep planning pull requests without deploying
merges — useful while you are still reading the plans.

## What Cargo needs from the repository

* **`@cargo-ai/cdk` as a dependency.** Cargo runs the version your repository
  pins, not one of its own, so a plan is the same diff you get locally.
* **A committed [`cargo.json`](https://docs.getcargo.ai/get-started/project-layout#cargojson)** in the
  connected directory, and **a committed `cargo.state.json`** beside it pointing
  at the state you connected. See [State & drift](https://docs.getcargo.ai/deploy/state-and-drift.md).
* **A lockfile**, so dependencies install the same way every run.

## Limits worth knowing

* **Pull requests from forks are not planned.** Planning means running that
  branch's code, and a fork is somebody else's.
* **`secret()` values are not available.** They resolve from a local `.env`,
  which a Cargo run does not have. Use
  [`workspaceEnv()`](https://docs.getcargo.ai/deploy/deploying) for anything a deploy needs to resolve.
* **Private npm dependencies are not supported yet.**

> [!NOTE]
>
> Prefer to run this in your own CI? Everything above is `cargo-ai project plan`
> and `cargo-ai project deploy` — see [Deploying](https://docs.getcargo.ai/deploy/deploying.md). The
> connected-repository path is the same two commands, run by Cargo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.