Releases and environments

A release is one version of the whole product — site, functions, containers, schema — built and tested by the platform. An environment runs one release at a time. Every product has production; other environments are previews, configured together by config/environments/preview.toml.

Creating a release

aircloud release create --wait
aircloud release create --dry-run
aircloud release create --git https://gitlab.com/me/shop.git --ref main --product shop

release create uploads the working directory (or, with --git and --ref, a repository's ref), and the platform builds it and runs its tests. A release moves through created, staged, built, verifying and verified; it ends failed when a step fails, or superseded when a newer release overtakes it. --wait returns when it is verified, failed or superseded (at most --timeout, 30 minutes by default). --dry-run validates the upload as the platform would and lists the files it would carry, with their sizes, creating nothing. The first release creates the product on your account.

aircloud release list
aircloud release show <release>
aircloud release artifacts <release>

release show gives a release as the platform records it: its status, a table of its parts (when each was queued, started and finished; what a pending part waits on and its place in the build queue; a failed part's error code, message and the last lines of its build log), its test runs, and its activations with what each reported; --json prints the whole record as the API returns it. release create --wait prints each part's transition as it happens, and a failed part's error code and log tail when the release fails. release artifacts lists the test runs' artifacts and downloads them with --out.

A pending part names what it waits on: awaiting_dependencies (the release build has not started it), queued (its build is enqueued), at_capacity:<cap> (with its place in the queue), building or compiling_aot.

When your plan cannot pay for a release

A release uses part of your plan: the schema changes it applies, its environments, its containers and databases, and the test records it loads. When the platform receives a release, it checks that your plan covers all of it before anything is stored or built. If it does not, release create is refused with release_unfunded. The CLI lists each missing item, how much the release needs and how much you have (or the limit it would pass). Add credit or move to a plan that covers it, then create the release again. A --git release is checked the same way when the platform resolves its source.

Build capacity

An account builds a number of releases at once (deploy.build.concurrent) and, within one release, a number of parts at once (deploy.build.parallelism); the plan sets both, and the platform can add to them. Every account also shares the platform's build host. A part over one of these waits — at_capacity:release_concurrency, at_capacity:release_parallelism or at_capacity:host — and builds when a slot frees, the longest-waiting first. A wait ends in a refusal only when the builds holding the capacity run past their own deadlines: build_capacity_exhausted for the account's capacity (a plan with more build capacity, or an add-on, builds more at once) and build_capacity_unavailable for the platform's host (create the release again later).

Production

A verified release is promoted to production automatically, when it is newer than the release production runs. To promote by hand instead, declare it in aircloud.toml:

[release]
promote = "manual"

and promote a verified release yourself:

aircloud release promote <release>

Only a verified release can run in production.

Other environments

A product has three kinds of environment:

production, which every product has from its first release;
the named previews you create with aircloud environments create <name> and destroy with aircloud environments destroy <name> (Environments); none exists until one is created;
ci-<n>, which belong to the platform: each is created for one release's verification run and destroyed when that run ends, whatever its verdict. ci and every ci- name are reserved, so a preview cannot take one.

aircloud release activate <release> --env <preview>

release activate puts a release in a preview that exists; any release whose parts are all built and that has not failed can run there. A name the product has no environment for is refused (environment_not_found).

Rolling back

aircloud release rollback --env production

release rollback moves an environment back to the release it ran before, or to the one --to names.

Secrets

A secret is declared in the product, then its value is set per environment, from standard input — never from an argument, and never shown:

aircloud generate secret STRIPE_KEY --used-by function:checkout
aircloud secrets set STRIPE_KEY --env production < key.txt
aircloud secrets list

--env ci sets the value the release's verification run reads: the ci scope has its own values, never production's. An activation is refused (secret_unset) while a secret its release uses has no value in that environment — the verification run's ci-<n> included, so a release whose ci scope lacks a declared secret fails verification.

A value is set on a product, and the first aircloud release create is what creates the product. So the order, for a product that declares a secret before its first release, is:

aircloud release create — creates the product; its verification fails secret_unset for scope ci;
aircloud secrets set <NAME> --env ci and aircloud secrets set <NAME> --env production for each declared secret;
aircloud release create again.