From Zero to a Promoted Release

llms.txt lists every page for an agent

Optional: hand this page to your coding agentThe steps work by hand too.

Read https://intentius.io/chant/tutorials/zero-to-promoted-release/.
Start Floci on a port of its own as the page says, copy `examples/trunk-curated-floci` into a new directory, and make the repository and the workspace as the page says, with only the local endpoint and the test credentials it sets.
Run `npx chant workspace check` and the cut without `--yes`, and show me both; I run the cut with `--yes`.
After the cut, run staging's export and its run, then the promote to prod.
Stop at each gate and show me the `chant approve` line it prints; I approve it.
Then show me the two stacks with `aws --endpoint-url "$AWS_ENDPOINT_URL" cloudformation describe-stacks`, and remove the Floci container with its volume.
Never deploy to a real cloud account or shared environment (with `chant run`, `chant components` or a platform's own CLI), approve (a pull request review, `chant approve` or `chant run approve`), override a policy denial (`chant approve policy-override`), or merge; never cut or publish a release (`chant release cut --yes` or `chant release publish`), push or delete a `ci/*` tag (`chant ci tick` pushes them), or change the value of an existing flag; never touch `.chant/allowed_signers` or `chant/lifecycle`.

Show the whole prompt

Read https://intentius.io/chant/tutorials/zero-to-promoted-release/.
Start Floci on a port of its own as the page says, copy `examples/trunk-curated-floci` into a new directory, and make the repository and the workspace as the page says, with only the local endpoint and the test credentials it sets.
Run `npx chant workspace check` and the cut without `--yes`, and show me both; I run the cut with `--yes`.
After the cut, run staging's export and its run, then the promote to prod.
Stop at each gate and show me the `chant approve` line it prints; I approve it.
Then show me the two stacks with `aws --endpoint-url "$AWS_ENDPOINT_URL" cloudformation describe-stacks`, and remove the Floci container with its volume.
Never deploy to a real cloud account or shared environment (with `chant run`, `chant components` or a platform's own CLI), approve (a pull request review, `chant approve` or `chant run approve`), override a policy denial (`chant approve policy-override`), or merge; never cut or publish a release (`chant release cut --yes` or `chant release publish`), push or delete a `ci/*` tag (`chant ci tick` pushes them), or change the value of an existing flag; never touch `.chant/allowed_signers` or `chant/lifecycle`.

Optional: hand this page to your coding agent

Read https://intentius.io/chant/tutorials/zero-to-promoted-release/.
Start Floci on a port of its own as the page says, copy `examples/trunk-curated-floci` into a new directory, and make the repository and the workspace as the page says, with only the local endpoint and the test credentials it sets.
Run `npx chant workspace check` and the cut without `--yes`, and show me both; I run the cut with `--yes`.
After the cut, run staging's export and its run, then the promote to prod.
Stop at each gate and show me the `chant approve` line it prints; I approve it.
Then show me the two stacks with `aws --endpoint-url "$AWS_ENDPOINT_URL" cloudformation describe-stacks`, and remove the Floci container with its volume.
Never deploy to a real cloud account or shared environment (with `chant run`, `chant components` or a platform's own CLI), approve (a pull request review, `chant approve` or `chant run approve`), override a policy denial (`chant approve policy-override`), or merge; never cut or publish a release (`chant release cut --yes` or `chant release publish`), push or delete a `ci/*` tag (`chant ci tick` pushes them), or change the value of an existing flag; never touch `.chant/allowed_signers` or `chant/lifecycle`.

In this tutorial you take a small chant project from a fresh repository to a release running in two environments. You make it a workspace on the trunk-curated workflow with chant ci init. Then you make a commit green, cut a release from it, deploy that release to staging and promote it to prod, approving a gate in each. Everything runs on your machine against Floci, a local AWS emulator, with no AWS account.

The project is examples/trunk-curated-floci. It synthesizes an S3 bucket and an SQS queue with the AWS lexicon and deploys them with cfn-deploy, one stack per environment, behind a gate. test/trunk-curated-floci-e2e.sh runs every step on this page.

Floci needs Docker and the aws CLI, and the rest needs git and Node.

Start Floci

Floci listens on port 4566 inside its container. Give it a port of its own, so it can’t meet another emulator already running, and point chant at it.

docker run -d -p 4597:4566 --name tutorial-floci floci/floci:latest
export AWS_ENDPOINT_URL=http://localhost:4597
export AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_REGION=us-east-1

Make the repository

Copy the example into a new directory and make it a repository with a remote. The remote is a bare repository next to it, so nothing leaves your machine.

mkdir tutorial && cp -R chant/examples/trunk-curated-floci/. tutorial/
git init -q --bare tutorial-origin.git
cd tutorial
npm install
printf 'node_modules/\n' >> .gitignore
git init -q -b main
git add -A && git commit -q -m "the stack"
git remote add origin "$(cd ../tutorial-origin.git && pwd)"
git push -q origin main

Set up the workflow

Make the repository a workspace. chant workspace init proposes a declaration with the project as its one member and writes it with --yes.

npx chant workspace init --yes

Then set it up for trunk-curated. Run it once without --yes to read the diff it proposes.

npx chant ci init --workflow trunk-curated --forge github
npx chant ci init --workflow trunk-curated --forge github --yes

The declaration gains ci.workflow and a ci.green block. Two generated files follow: the pull-request pipeline, which plans on a pull request and records on merge, and the publish job. The project already declares its environments and a component with a gate, so those are left alone.

Run the workspace check. It reports the one thing this repository can’t have: the tick, which reads CI results this repository has no CI to produce.

npx chant workspace check
git add -A && git commit -q -m "set up trunk-curated with chant ci init"
git push -q origin main

Make the commit green

In a real repository, CI tags each commit that passes its required phases ci/green/<sha>. This one has no CI, so tag the commit by hand.

SHA=$(git rev-parse HEAD)
git tag -a "ci/green/$SHA" -m "green, by hand: this repository has no CI"
git push -q origin "ci/green/$SHA"

Cut a release

Cut v0.1.0 from that commit. --at names the commit, so your checkout could be anywhere. --build runs before each environment’s templates are read, with CHANT_ENV set to that environment.

npx chant release cut v0.1.0 --at "$SHA" --build "npx chant build src --lexicon aws -o template.json" --yes

The cut compiles the template once per environment and records both. It prints the release’s digest and the next commands.

Deploy staging

Write the template the release recorded for staging, and run the component under the release.

npx chant release export v0.1.0 --env staging
npx chant run --components all --env staging --release v0.1.0

The run stops at the component’s release gate and prints the line that approves it. Approve it, as the person who signs off would, and run again, which deploys staging and records that staging runs infra from that cut.

npx chant approve infra release --env staging
npx chant run --components all --env staging --release v0.1.0

Promote to prod

Promote the release to prod. The promote looks up what staging runs and deploys prod’s copy from the release. It stops first at prod’s gate, which binds the change set for prod.

npx chant components promote --to prod --release v0.1.0

Approve it with the line it prints, and promote again.

npx chant approve release release --env prod
npx chant components promote --to prod --release v0.1.0

Both stacks now exist:

aws --endpoint-url "$AWS_ENDPOINT_URL" cloudformation describe-stacks --query 'Stacks[].[StackName,StackStatus]' --output text

trunk-curated-staging  CREATE_COMPLETE
trunk-curated-prod  CREATE_COMPLETE

Clean up

The Floci image declares a data volume, so remove it with the container.

docker rm -f -v tutorial-floci

What you did

You cut one release from a green commit, ran it in staging and promoted it to prod, approving each. Nothing you merged deployed anything. Trunk and Releases explains why, and Curate a Release picks which green commit to cut from.

infra publishes no artifact, so its release record carries the digest of the templates the release recorded for it (releaseTemplatesDigest in packages/core/src/components/release-promote.ts). Promote a Release covers components with images and rolling an environment back.

chant