Skip to main content
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:
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. 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 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 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 in the connected directory, and a committed cargo.state.json beside it pointing at the state you connected. See State & drift.
  • 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() for anything a deploy needs to resolve.
  • Private npm dependencies are not supported yet.
Prefer to run this in your own CI? Everything above is cargo-ai project plan and cargo-ai project deploy — see Deploying. The connected-repository path is the same two commands, run by Cargo.