# 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 ```sh 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. ```sh aircloud release list aircloud release show aircloud release artifacts ``` `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:` (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`: ```toml [release] promote = "manual" ``` and promote a verified release yourself: ```sh aircloud release promote ``` 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 ` and destroy with `aircloud environments destroy ` ([Environments](environments.md)); none exists until one is created; - `ci-`, 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. ```sh aircloud release activate --env ``` `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 ```sh 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: ```sh 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-` 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: 1. `aircloud release create` — creates the product; its verification fails `secret_unset` for scope `ci`; 2. `aircloud secrets set --env ci` and `aircloud secrets set --env production` for each declared secret; 3. `aircloud release create` again. --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e.