@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.
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: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 thecargo: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 runscargo-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-impactlabel. - It runs on no more records now than that preview allows.
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/cdkas 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.jsonin the connected directory, and a committedcargo.state.jsonbeside 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. UseworkspaceEnv()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.
