@gambi97/keel-cli 0.3.4 → 0.3.6

package/README.md

@@ -62,7 +62,8 @@ non-empty repository is reported immediately, and only that answer is asked
 again). It picks up `SCW_*` / `INFISICAL_*` / `GITHUB_TOKEN` from your
 environment as defaults, then shows a **complete summary of what it will
 create and where**. Nothing is touched before you confirm. When it finishes, push to `main` (or merge the
-first PR) and the pipeline provisions the infrastructure.
+first PR) and the pipeline provisions the non-production infrastructure; a
+version tag (`vX.Y.Z`) promotes to production.
 
 Non-interactive and dry-run:
 
@@ -150,14 +151,16 @@ flowchart TD
     CLI -->|creates state bucket| SCW[(Scaleway<br/>Object Storage)]
     CLI -->|creates repo, secrets,<br/>variables, branch rules| GH[GitHub repo]
     CLI -->|creates project, envs,<br/>placeholder secrets| INF[Infisical]
-    GH -->|push to main| ACT[GitHub Actions]
-    ACT -->|terraform apply| PROD[Scaleway:<br/>Container + SQL + Registry]
+    GH -->|merge to main| ACT[GitHub Actions]
+    GH -->|tag vX.Y.Z| ACT
+    ACT -->|apply non-prod / prod| PROD[Scaleway:<br/>Container + SQL + Registry]
     INF -.->|app secrets at runtime| PROD
 ```
 
 The CLI does the **bootstrap**, in seconds, on your machine. The first
 `terraform apply` runs **in CI** on the first push to `main`, so nobody needs
-local tooling or production credentials.
+local tooling or production credentials. Non-production environments deploy on
+every merge; production is promoted by pushing a version tag.
 
 ## What gets created, and when
 
@@ -167,7 +170,7 @@ local tooling or production credentials.
 | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Your machine | The generated repo: Terraform, workflows, README, initial git commit                                                                                                                                                                                              |
 | Scaleway     | One Object Storage bucket for Terraform state (versioned, with native state locking, restricted by a bucket policy to the identity behind your API key)                                                                                                           |
-| GitHub       | Repository (public or private) pushed to `main`; encrypted Actions secrets; Actions variables; one deployment environment per selected environment (`production` gated by manual approval); branch protection on `main`                                           |
+| GitHub       | Repository (public or private) pushed to `main`; encrypted Actions secrets; Actions variables; one deployment environment per selected environment (`production` promoted by a version tag); branch protection on `main`                                          |
 | Infisical    | A project with one environment per selected environment, seeded with `BASIC_AUTH_USER` / `BASIC_AUTH_PASSWORD` (non-production, random password), `DATABASE_URL` / `APP_URL` placeholders per environment, and `S3_*` placeholders when Object Storage is enabled |
 
 **Phase B: first deploy (Terraform in GitHub Actions, on push to `main`)**
@@ -190,7 +193,7 @@ my-app/
 ├── README.md                    # operating manual for the repo
 ├── .github/workflows/
 │   ├── terraform-plan.yml       # PR: fmt + validate + plan (every environment)
-│   ├── terraform-apply.yml      # main: apply each env in order; production gated
+│   ├── terraform-apply.yml      # merge to main: apply non-prod; tag vX.Y.Z: apply prod
 │   └── terraform-drift.yml      # weekly: read-only plan, opens an issue on drift
 ├── .keel/manifest.json          # committed record: keel version, contract version, options
 ├── versions.tf · providers.tf · backend.tf
@@ -222,8 +225,8 @@ day-2 work (scaling, rotating secrets, custom domains, troubleshooting). The
 short version of the first deploy:
 
 1. **Push to `main`** (or merge a PR): the pipeline provisions registry and
-   databases (and an Object Storage bucket, if enabled). Approve the
-   `production` gate when prompted.
+   databases for the non-production environments (and an Object Storage bucket,
+   if enabled). Production waits for a version tag (step 5).
 2. **Build and push your app image** to the registry endpoint from the apply
    output (replace `<env>` with your target environment):
    ```sh
@@ -234,9 +237,12 @@ short version of the first deploy:
 3. **Set `container_image`** in the tfvars and open a PR: the next apply
    creates the containers.
 4. **Replace the placeholder secrets** in Infisical with real values. The app
-   reads `DATABASE_URL`, `BASIC_AUTH_*` and (if enabled) `S3_*` from its
-   environment; non-production environments also receive `BASIC_AUTH_ENABLED=true`
-   and enforce it.
+   reads `DATABASE_URL`, `APP_URL`, `BASIC_AUTH_*` and (if enabled) `S3_*` from
+   its environment; non-production environments also receive
+   `BASIC_AUTH_ENABLED=true` and enforce it.
+5. **Release to production**: push a version tag — `git tag v1.0.0 && git push
+--tags` — and the production apply runs against that commit. A merge to
+   `main` never deploys production.
 
 ## Prerequisites
 
@@ -293,7 +299,9 @@ creating anything**.
 - Actions secrets are encrypted client-side (libsodium sealed box) before
   upload.
 - `main` is protected: force pushes and deletion blocked, PRs need a green
-  plan, production applies need manual approval.
+  plan. Production never deploys from a merge — it is gated behind a version
+  tag, a free promotion control that works on any GitHub plan (required-reviewer
+  rules need a paid plan on private repos) and lives auditably in the repo.
 - Terraform state lives in a private, versioned bucket with S3-native state
   locking (`use_lockfile`), so concurrent applies cannot corrupt it.
 - The state bucket is **restricted by a bucket policy** to the identity that
@@ -373,12 +381,13 @@ endpoints. Credentials live in Infisical, the container gets
 **Which environments do I get, and can I change them?**
 You choose at creation: production only, staging + production (default), or
 dev + staging + production — interactively or with `--environments`
-(e.g. `--environments prod` or `--environments dev,staging,prod`). Production
-is always gated by a manual approval; non-production environments enable Basic
-Auth by default. To add one to an existing repo later: add a `<env>.tfvars`
-(the plan and drift workflows discover environments from the tfvars files at
-the repo root automatically), an Infisical environment with the same slug, and
-a chained job in `terraform-apply.yml`.
+(e.g. `--environments prod` or `--environments dev,staging,prod`). Non-production
+environments deploy on merge to `main` and enable Basic Auth by default;
+production is promoted by pushing a version tag (`vX.Y.Z`), never by a merge. To
+add a non-production environment later: add a `<env>.tfvars` (the plan and drift
+workflows discover environments from the tfvars files at the repo root
+automatically), an Infisical environment with the same slug, and a `main`-gated
+job in `terraform-apply.yml`.
 
 **Can I extend the generated repo with my own Terraform?**
 Yes, and additions never edit generated files: drop a new `.tf` file at the

package/dist/bootstrap/github.js

@@ -24,18 +24,21 @@ export class GitHubError extends Error {
 export async function authenticate(token) {
     // Silence Octokit's own request logging: expected non-2xx responses (a 404
     // for a repo that does not exist yet, a 401 for a bad token) are handled
-    // here and would otherwise scribble over the prompt spinner.
+    // here and would otherwise scribble over the prompt spinner. The same sink
+    // is passed at the request layer too: @octokit/request reads
+    // `request.log` (falling back to console) for deprecation notices carried
+    // in response headers, bypassing the instance logger.
+    const silentLog = { debug: () => { }, info: () => { }, warn: () => { }, error: () => { } };
     const octokit = new Octokit({
         auth: token,
-        log: { debug: () => { }, info: () => { }, warn: () => { }, error: () => { } },
+        log: silentLog,
+        request: { log: silentLog },
     });
     let login;
-    let ownerId;
     let scopes;
     try {
         const { data, headers } = await octokit.users.getAuthenticated();
         login = data.login;
-        ownerId = data.id;
         scopes = headers['x-oauth-scopes'];
     }
     catch {
@@ -53,7 +56,7 @@ export async function authenticate(token) {
             }
         }
     }
-    return { octokit, owner: login, ownerId };
+    return { octokit, owner: login };
 }
 export async function createContext(github) {
     const identity = await authenticate(github.token);
@@ -209,11 +212,8 @@ export async function configureRepo(ctx, answers, infisicalProjectId) {
         INFISICAL_HOST: answers.infisical.host,
     };
     await setVariables(ctx, variables);
-    const warnings = [
-        await configureEnvironments(ctx, answers),
-        await protectMainBranch(ctx, answers),
-    ].filter((w) => w !== undefined);
-    return warnings.length > 0 ? warnings.join('\n\n') : undefined;
+    await configureEnvironments(ctx, answers);
+    return protectMainBranch(ctx, answers);
 }
 async function setSecrets(ctx, secrets) {
     await sodium.ready;
@@ -255,44 +255,20 @@ async function setVariables(ctx, variables) {
     }
 }
 /**
- * Each environment gets a GitHub deployment environment; gated ones (prod)
- * require a reviewer approval. Required reviewers need GitHub Enterprise Cloud
- * on private repositories — GitHub answers 422 there. Rather than strand the
- * bootstrap at its last step, fall back to an ungated environment and warn:
- * the environment still exists (deployments target it) but production will
- * auto-deploy on merge. Like the branch-protection miss, this degrades to a
- * warning instead of killing the run.
+ * Each environment gets a GitHub deployment environment, used by the apply
+ * workflow for deployment tracking and history. No reviewer gate is requested:
+ * production is promoted by a version tag — the tag IS the gate, free on every
+ * plan, while required reviewers would need GitHub Enterprise Cloud on private
+ * repositories and would only duplicate what the tag already enforces.
  */
 export async function configureEnvironments(ctx, answers) {
-    const ungated = [];
     for (const env of answers.environments) {
-        try {
-            await ctx.octokit.repos.createOrUpdateEnvironment({
-                owner: ctx.owner,
-                repo: ctx.repo,
-                environment_name: env.githubEnvironment,
-                ...(env.gated ? { reviewers: [{ type: 'User', id: ctx.ownerId }] } : {}),
-            });
-        }
-        catch (error) {
-            // Only the reviewer rule can trip the plan limit; re-throw anything else
-            // (and any failure on a non-gated environment, which asked for no rule).
-            if (!env.gated || error.status !== 422)
-                throw error;
-            await ctx.octokit.repos.createOrUpdateEnvironment({
-                owner: ctx.owner,
-                repo: ctx.repo,
-                environment_name: env.githubEnvironment,
-            });
-            ungated.push(env.githubEnvironment);
-        }
+        await ctx.octokit.repos.createOrUpdateEnvironment({
+            owner: ctx.owner,
+            repo: ctx.repo,
+            environment_name: env.githubEnvironment,
+        });
     }
-    if (ungated.length === 0)
-        return undefined;
-    return (`Created the ${ungated.join(', ')} environment(s) without the manual-approval gate: ` +
-        'required reviewers need GitHub Enterprise Cloud on private repositories, so production ' +
-        'will auto-deploy on merge to main. Make the repository public (reviewers are free there) ' +
-        'or upgrade the plan, then re-run to add the gate.');
 }
 /**
  * Require a green plan on PRs and forbid force-pushes/deletion of main.

package/dist/bootstrap/scaleway.js

@@ -33,6 +33,26 @@ export async function validateScalewayCredentials(scaleway) {
             `not ${organizationId}. Check --scw-organization-id.`, 'organization');
     }
 }
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Bucket-metadata calls made right after CreateBucket can race its propagation
+ * and answer NoSuchBucket for a bucket that provably exists (we created or
+ * Head-checked it moments before). Retry exactly that error with a short
+ * backoff; anything else is a real failure and is thrown immediately.
+ */
+export async function retryWhileBucketPropagates(fn, attempts = 5, baseDelayMs = 1000) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (error.name !== 'NoSuchBucket' || attempt >= attempts) {
+                throw error;
+            }
+            await sleep(attempt * baseDelayMs);
+        }
+    }
+}
 function s3Client(answers) {
     return new S3Client({
         region: answers.region,
@@ -107,13 +127,14 @@ async function lockDownStateBucket(client, bucket, answers) {
         ],
     };
     try {
-        await client.send(new PutBucketPolicyCommand({ Bucket: bucket, Policy: JSON.stringify(policy) }));
+        await retryWhileBucketPropagates(() => client.send(new PutBucketPolicyCommand({ Bucket: bucket, Policy: JSON.stringify(policy) })));
         return undefined;
     }
     catch (error) {
         return (`Could not apply a policy to bucket "${bucket}" ` +
             `(${error instanceof Error ? error.message : String(error)}); ` +
-            'the state bucket was NOT restricted to your identity.');
+            'the state bucket was NOT restricted to your identity. ' +
+            'Re-run keel to retry this step.');
     }
 }
 /**
@@ -144,10 +165,10 @@ export async function ensureStateBucket(answers) {
         try {
             await client.send(new CreateBucketCommand({ Bucket: bucket }));
             // Versioning protects the state history against accidental overwrites.
-            await client.send(new PutBucketVersioningCommand({
+            await retryWhileBucketPropagates(() => client.send(new PutBucketVersioningCommand({
                 Bucket: bucket,
                 VersioningConfiguration: { Status: 'Enabled' },
-            }));
+            })));
             created = true;
         }
         catch (createError) {

package/dist/config.js

@@ -11,7 +11,6 @@ const ENV_DEFAULTS = {
         displayName: 'Development',
         githubEnvironment: 'dev',
         production: false,
-        gated: false,
         minScale: 0,
         maxScale: 1,
     },
@@ -19,7 +18,6 @@ const ENV_DEFAULTS = {
         displayName: 'Staging',
         githubEnvironment: 'staging',
         production: false,
-        gated: false,
         minScale: 0,
         maxScale: 1,
     },
@@ -27,7 +25,6 @@ const ENV_DEFAULTS = {
         displayName: 'Production',
         githubEnvironment: 'production',
         production: true,
-        gated: true,
         minScale: 0,
         // Start small: one instance is enough to go live and costs the least;
         // raising the ceiling later is a one-line prod.tfvars change.
@@ -50,12 +47,25 @@ export const DEFAULT_ENV_PRESET = 'staging+prod';
  * Lock a resume's configuration to what the repo was generated with. Scaling
  * is intentionally not carried: it only shapes the tfvars, which are already
  * generated on any run that has a manifest, so post-generate steps never read it.
+ *
+ * The GitHub repo identity is locked too: on resume the target repository is
+ * already decided (keel created and pushed it), so the picker must not run and
+ * must never frame the project's own — now non-empty — repo as "create a new
+ * one". Older manifests without a github block fall back to the project name,
+ * which is the repo default and the only repository the project could own. An
+ * explicit --repo-name still wins (the established flag-precedence rule).
  */
 export function hydrateConfigFromManifest(partial, manifest) {
     partial.region = manifest.region;
     partial.environments = manifest.environments;
     partial.objectStorage = manifest.options.objectStorage;
     partial.basicAuth = manifest.options.basicAuth;
+    if (!partial.github.repoName) {
+        partial.github.repoName = manifest.github?.repoName ?? manifest.projectName;
+    }
+    if (partial.github.repoPrivate === undefined && manifest.github?.repoPrivate !== undefined) {
+        partial.github.repoPrivate = manifest.github.repoPrivate;
+    }
 }
 export class ConfigError extends Error {
 }
@@ -210,8 +220,7 @@ export function resolveEnvironments(slugs, basicAuth, overrides) {
             displayName: def.displayName,
             githubEnvironment: def.githubEnvironment,
             production: def.production,
-            gated: def.gated,
-            // Basic Auth is a non-production safety net; production is never gated by it.
+            // Basic Auth is a non-production safety net; production never has it.
             basicAuth: def.production ? false : basicAuth,
             minScale,
             maxScale,

package/dist/generate.js

@@ -26,6 +26,12 @@ function renderManifest(answers) {
             objectStorage: answers.objectStorage,
             basicAuth: answers.basicAuth,
         },
+        // Recorded so a resume locks the repository instead of re-running the
+        // picker; see hydrateConfigFromManifest.
+        github: {
+            repoName: answers.github.repoName,
+            repoPrivate: answers.github.repoPrivate,
+        },
     };
     return `${JSON.stringify(manifest, null, 2)}\n`;
 }
@@ -99,16 +105,32 @@ function isSpecial(rel) {
  * in deploy order, each `needs:` the previous so applies run sequentially.
  */
 function renderApplyWorkflow(source, answers, globalTokens) {
-    const header = renderContent(readFileSync(join(source, '_partials/apply-header.yml'), 'utf8'), globalTokens, '_partials/apply-header.yml');
+    // Non-production environments deploy on merge to main (chained in order);
+    // production is promoted by a version tag. The triggers and the per-job
+    // guards are assembled from which environments exist, so a prod-only repo
+    // has no branch trigger and a prod-less selection has no tag trigger.
+    const nonProd = answers.environments.filter((env) => !env.production);
+    const prod = answers.environments.find((env) => env.production);
+    const triggers = [];
+    if (nonProd.length > 0)
+        triggers.push('    branches: [main]');
+    if (prod)
+        triggers.push('    tags: ["v*.*.*"]');
+    const header = renderContent(readFileSync(join(source, '_partials/apply-header.yml'), 'utf8'), { ...globalTokens, __APPLY_TRIGGERS__: triggers.join('\n') }, '_partials/apply-header.yml');
     const jobTemplate = readFileSync(join(source, '_partials/apply-job.yml'), 'utf8');
-    const jobs = answers.environments.map((env, i) => {
-        const previous = answers.environments[i - 1];
-        return renderContent(jobTemplate, {
-            __ENV_SLUG__: env.slug,
-            __GH_ENVIRONMENT__: env.githubEnvironment,
-            __NEEDS_LINE__: previous ? `    needs: apply-${previous.slug}\n` : '',
-        }, '_partials/apply-job.yml');
+    const renderJob = (env, applyIf, needs) => renderContent(jobTemplate, {
+        __ENV_SLUG__: env.slug,
+        __GH_ENVIRONMENT__: env.githubEnvironment,
+        __APPLY_IF__: applyIf,
+        __NEEDS_LINE__: needs,
+    }, '_partials/apply-job.yml');
+    const jobs = nonProd.map((env, i) => {
+        const previous = nonProd[i - 1];
+        return renderJob(env, "github.ref == 'refs/heads/main'", previous ? `    needs: apply-${previous.slug}\n` : '');
     });
+    if (prod) {
+        jobs.push(renderJob(prod, "startsWith(github.ref, 'refs/tags/')", ''));
+    }
     return header + jobs.join('\n');
 }
 function renderContent(content, tokens, file) {

package/dist/index.js

@@ -7,7 +7,7 @@ import { CI_SECRET_NAMES, CI_VARIABLE_NAMES, resourceName } from './contracts.js
 import { generateProject, GenerateError, readManifest } from './generate.js';
 import { toolVersion } from './meta.js';
 import { confirmSummary, fillMissing } from './prompts.js';
-import { isDone, loadState, markDone, STATE_FILE, stepData, } from './state.js';
+import { isDone, loadState, markDone, STATE_FILE, stepData, stepWarning, } from './state.js';
 import { cancel, intro, log, outro, renderNextSteps, renderSummary, withSpinner } from './ui.js';
 import { ensureStateBucket, validateScalewayCredentials } from './bootstrap/scaleway.js';
 import { bootstrapInfisical, validateInfisical } from './bootstrap/infisical.js';
@@ -316,8 +316,13 @@ async function runBootstrap(answers, state, options) {
             log.info(step.skipMessage);
             continue;
         }
+        // A step that degraded with a warning last run is re-run (idempotent) so
+        // the degraded part can heal — e.g. a bucket policy that raced creation.
+        if (stepWarning(state, step.name)) {
+            log.info('Previous run finished this step with a warning — retrying it.');
+        }
         const result = await withSpinner(step.label(answers, ctx), () => step.run(answers, ctx, state));
-        markDone(answers.targetDir, state, step.name, result?.data);
+        markDone(answers.targetDir, state, step.name, result?.data, result?.warning);
         if (result?.warning)
             log.warn(result.warning);
     }

package/dist/prompts.js

@@ -55,7 +55,7 @@ export async function fillMissing(partial, options) {
     const resuming = manifest !== undefined && manifest.projectName === out.projectName;
     if (manifest && resuming) {
         hydrateConfigFromManifest(out, manifest);
-        log.info(`Resuming "${out.projectName}" — region, environments and options are locked to its .keel manifest.`);
+        log.info(`Resuming "${out.projectName}" — repository, region, environments and options are locked to its .keel manifest.`);
     }
     // Each block opens with a "┌ <Provider>" section corner and closes with a
     // "└ <Provider> connected — …" line, so every question flows inside its own

package/dist/state.js

@@ -18,10 +18,15 @@ export function saveState(targetDir, state) {
     writeFileSync(join(targetDir, STATE_FILE), `${JSON.stringify(state, null, 2)}\n`);
 }
 export function isDone(state, step) {
-    return state.steps[step] !== undefined;
+    const record = state.steps[step];
+    return record !== undefined && record.warning === undefined;
 }
-export function markDone(targetDir, state, step, data) {
-    state.steps[step] = data ? { data } : {};
+/** The warning a previous run recorded for this step, if it degraded. */
+export function stepWarning(state, step) {
+    return state.steps[step]?.warning;
+}
+export function markDone(targetDir, state, step, data, warning) {
+    state.steps[step] = { ...(data ? { data } : {}), ...(warning ? { warning } : {}) };
     saveState(targetDir, state);
 }
 export function stepData(state, step, key) {

package/dist/ui.js

@@ -59,7 +59,7 @@ export function renderSummary(answers, dryRun) {
     for (const env of answers.environments) {
         const flags = [
             `scale ${env.minScale}-${env.maxScale}`,
-            env.gated ? 'manual approval' : 'auto-deploy',
+            env.production ? 'deploys on version tag' : 'deploys on merge to main',
             env.basicAuth ? 'basic auth' : null,
         ]
             .filter(Boolean)
@@ -79,9 +79,10 @@ export function renderNextSteps(answers, repoUrl, containerUrlHint) {
         `     registry created by the first pipeline run (${containerUrlHint}).`,
         `  2. Replace the placeholder secrets in Infisical (${answers.infisical.host})`,
         `     project "${answers.infisical.projectName}" with real values.`,
-        `  3. Push to main (or merge a PR) to trigger the first terraform apply:`,
+        `  3. Push to main (or merge a PR) to deploy the non-production environments:`,
         `     ${repoUrl}/actions`,
         `  4. Set container_image in ${answers.environments.map((e) => `${e.slug}.tfvars`).join(' / ')} once an image exists.`,
+        `  5. Release to production with a version tag: git tag v1.0.0 && git push --tags`,
         '',
         `Repository: ${repoUrl}`,
     ].join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gambi97/keel-cli",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "One command from zero to a production-shaped serverless infrastructure on Scaleway (Terraform + GitHub Actions + Infisical). Only Node required.",
   "keywords": [
     "keel",

package/templates/README.md

@@ -40,12 +40,18 @@ Credentials live in GitHub Actions encrypted secrets (CI) and in Infisical
 
 ```
 PR to main        -> terraform fmt + validate + plan (every environment), shown as PR checks
-merge/push main   -> apply each environment in order; any gated environment (production) waits for manual approval
+merge/push main   -> apply non-production environments in order (dev, staging)
+tag vX.Y.Z        -> apply production (the commit the tag points at)
 ```
 
 - `main` is protected: PRs need a green plan, force pushes are blocked.
-- Environments apply in order, each `needs:` the previous one; a gated
-  environment (production) waits for approval on its GitHub Environment.
+- Non-production environments apply on every merge to `main`, in order, each
+  `needs:` the previous one — a continuously-deployed staging.
+- **Production is promoted by a version tag**, not by a merge: push a tag like
+  `v1.2.0` and the production apply runs against that commit. The tag is the
+  gate — it works on any GitHub plan (unlike required-reviewer rules, which
+  need a paid plan on private repos), lives in the repo, and rolling back is
+  re-tagging an earlier commit. Cut one with `git tag v1.2.0 && git push --tags`.
 - After each apply, the pipeline syncs the secrets Terraform produced to
   Infisical for that environment: a ready-to-use Postgres `DATABASE_URL`
   (whose credential is a dedicated IAM application that can only read/write
@@ -60,9 +66,10 @@ merge/push main   -> apply each environment in order; any gated environment (pro
 ## First deploy
 
 1. **Merge or push to `main`.** The first pipeline run creates registry and
-   databases (and the Object Storage bucket, if enabled). The Serverless
-   Container is intentionally skipped until an image exists (`container_image`
-   is empty), so the first apply is green.
+   databases for the non-production environments (and the Object Storage
+   bucket, if enabled). The Serverless Container is intentionally skipped until
+   an image exists (`container_image` is empty), so the first apply is green.
+   Production waits for a version tag (step 5).
 
 2. **Build and push the app image** (any Dockerfile, listening on port 8080
    by default), replacing `<env>` with your target environment (e.g. staging):
@@ -90,7 +97,19 @@ merge/push main   -> apply each environment in order; any gated environment (pro
 
    Every secret in the Infisical environment is injected into the container
    as a secret environment variable, so adding an app secret is: add it in
-   Infisical, re-run the apply (any merge to `main`).
+   Infisical, re-run the apply (a merge to `main` for non-prod, a new tag for
+   production).
+
+5. **Release to production**: once staging looks good, cut a version tag on the
+   commit you want live and push it:
+
+   ```sh
+   git tag v1.0.0
+   git push --tags
+   ```
+
+   The production apply runs against that commit. Nothing reaches production
+   without a tag, so a merge to `main` can never deploy it by accident.
 
 ## Basic Auth on non-production environments
 
@@ -115,13 +134,13 @@ environment enables it is the `enable_basic_auth` flag in its `<env>.tfvars`.
   secrets (repo Settings > Secrets and variables > Actions).
 - **Add a custom domain**: add a `scaleway_container_domain` resource in
   `modules/app_stack` pointing at the container, plus your DNS record.
-- **Add an environment**: add a `<env>.tfvars` at the repo root (the plan and
-  drift workflows discover environments from the tfvars files automatically),
-  create an Infisical environment with the same slug, and add a job in
-  `.github/workflows/terraform-apply.yml` (mirror an existing one and set its
-  `needs:` to chain after the previous environment). Note: the new `plan
-  (<env>)` check becomes required on `main` only after you add it in the
-  branch-protection settings.
+- **Add a non-production environment**: add a `<env>.tfvars` at the repo root
+  (the plan and drift workflows discover environments from the tfvars files
+  automatically), create an Infisical environment with the same slug, and add a
+  job in `.github/workflows/terraform-apply.yml` — mirror an existing non-prod
+  job (`if: github.ref == 'refs/heads/main'`) and set its `needs:` to chain
+  after the previous one. Note: the new `plan (<env>)` check becomes required on
+  `main` only after you add it in the branch-protection settings.
 - **Pin provider versions**: after any local `terraform init`, commit the
   generated `.terraform.lock.hcl` so CI resolves the exact same provider
   builds on every run.

package/templates/_partials/apply-header.yml

@@ -1,13 +1,19 @@
 name: Terraform apply
 
+# Non-production environments deploy on every merge to main; production is
+# promoted by pushing a version tag (vX.Y.Z), so a merge never touches prod.
+# Tag-based promotion is the free, git-native gate (no paid environment rule):
+# the tag lives in the repo, is auditable, and rolling back is re-tagging.
 on:
   push:
-    branches: [main]
+__APPLY_TRIGGERS__
 
 permissions:
   contents: read
 
 concurrency:
+  # Serialize all applies against the shared state bucket; a tag deploy and a
+  # main deploy never run at the same time.
   group: terraform-apply
   cancel-in-progress: false
 

package/templates/_partials/apply-job.yml

@@ -1,8 +1,9 @@
   apply-__ENV_SLUG__:
     name: apply (__ENV_SLUG__)
     runs-on: ubuntu-latest
-__NEEDS_LINE__    # The GitHub environment may carry a required-reviewer rule, gating this job.
-    environment: __GH_ENVIRONMENT__
+    # Non-prod runs on merge to main; prod runs only on a version tag.
+    if: __APPLY_IF__
+__NEEDS_LINE__    environment: __GH_ENVIRONMENT__
     steps:
       - uses: actions/checkout@v4