> ## 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 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 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. **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. 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 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](/deploy/state-and-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()`](/deploy/deploying) 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](/deploy/deploying). 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.