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

Connect GitHub and install the Cargo GitHub app

Both from Settings → Connectors → GitHub. The connector is your GitHub account; the app is what lets Cargo read the commit and write the check. Install the app on the repository.
2

Connect it to the project

Settings → States, open the project’s state, and pick the GitHub connector, the repository, the branch that deploys and the directory that holds cargo.state.json. Connecting is refused unless the app is installed and the connector’s account is an admin of the repository — that check is what stops another workspace from claiming it.
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 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. 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.state.json 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.