Deploy Go-to-Market Changes When a Pull Request Merges

To deploy go-to-market changes when a pull request merges, connect the GitHub repository that holds your Cargo project in Settings → States: Cargo then plans every pull request as a comment and a check, and runs cargo-ai project deploy --yes on every push to the production branch. There is no workflow file to write and no Cargo API token to store in GitHub.

Your data models, plays, tools and agents are already TypeScript in a repository (if not, start here). This step makes the merge button the deploy button.

What the repository needs #

npm install -g @cargo-ai/cli
cargo-ai login --email you@company.com
cargo-ai project init acme-gtm      # creates the deploy state and commits its pointer
cd acme-gtm && git push             # push to GitHub

Cargo runs the project with the @cargo-ai/cdk version your repository pins, so the plan on the pull request is the same diff you get locally. Three things must be committed:

• @cargo-ai/cdk as a dependency.
• cargo.state.json, the pointer to the deploy state held in your workspace. A project from before states moved into the workspace moves with cargo-ai project state create.
• A lockfile, so every run installs the same dependencies.

Connect it #

1. Settings → Connectors → GitHub: connect your GitHub account and install the Cargo GitHub app on the repository. The installation must have accepted contents: read, checks: write and pull_requests: write, and the push and pull_request events; connecting is refused, with a link to the app’s settings, until it has.
2. Settings → States: open the project’s state and pick the connector, the repository, the production branch and the directory that holds cargo.state.json. Optionally pick the service user deploys run as.
3. Open a pull request. Cargo comments the plan on it.

Connecting is refused unless the connector’s GitHub account is an admin of the repository, which is what stops another workspace from claiming it. One repository directory can be connected to one state.

What a pull request does #

Nothing to the workspace. A plan compiles the branch in a sandbox and diffs it against the deploy state, with no Cargo credential: the sandbox gets a copy of the state and a read-only clone token for that one repository. The comment lists the resources that change, resources dropped from code as Prune, and what the merge will send and spend. The check fails when the project does not compile, or when the merge’s impact needs approval.

A repository can hold several projects: connect each directory separately, and each gets its own check and comment. A pull request plans only the projects whose directory changed, plus all of them when the root package.json, package-lock.json or cargo.state.json changed.

What a merge does #

A push to the production branch runs cargo-ai project deploy --yes on that commit:

• As a service user, never a person. Cargo mints a credential for the run and revokes it when the run ends; it expires after 30 minutes as a backstop. Without a choice at connect time, Cargo creates a service user for the repository with your permissions.
• In order. Deploys of one project run one at a time. When several wait, only the newest applies, since it contains the others, and a commit older than the one deployed is never applied.
• Against the last deployed commit. A project deploys when its directory changed since the commit it last deployed, so a change whose deploy failed or was paused goes out with the next push.
• Without deleting. Resources removed from code stay live until someone runs cargo-ai project deploy --prune.

Every plan and deploy is listed on the project’s state in Settings → States, with its status: queued, running, success, error or cancelled. Turn Deploy on push off to keep planning pull requests without deploying merges.

Who can deploy once it is connected #

With Deploy on push on, Cargo refuses a cargo-ai project deploy from anyone but the connection’s service user, and --force does not get past it. That stops a second deployer from starting executions no pull request approved. If your repository still has .github/workflows/cargo-deploy.yml from an older template, delete it: Cargo warns about it when you connect. plan, import, pull and rollback keep working from a laptop. To deploy by hand during an incident, turn Deploy on push off.

Limits #

• Pull requests from forks are not planned.
• secret() values resolve from a local .env, which a Cargo run does not have. Use workspaceEnv() for anything a deploy must resolve.
• Private npm dependencies are not supported yet.
• Anyone who can push to the production branch decides what the service user changes. Give it only what the project deploys, and protect the branch the way you protect production.

Prefer your own CI? The connected path is the same cargo-ai project plan and cargo-ai project deploy your pipeline can run. Full reference: GitHub deploys in the Cargo docs. The rest of the lifecycle is in GTM as code: the complete guide.