CI/CD Variables

The template's pipeline is configured with CI/CD variables. Set them in Settings → CI/CD → Variables in GitLab. On GitHub, set them as Actions variables, except the ones the workflows map from secrets (see CI/CD → GitHub Actions).

If you deploy with the template's pipeline, you only set variables. bin/devops/k8s.sh turns them into the chart's values and runs Helm. The Helm value column below says where each one ends up, so you can read it alongside Kubernetes & Helm. A — means the variable steers the pipeline and sets no chart value.

Minimum for a new site

The deploy works out the settings that would otherwise be the same on every site: CWA_CI_INGRESS_ENABLED, CORS_ALLOW_ORIGIN, TRUSTED_HOSTS, MERCURE_CORS_ORIGIN and DATABASE_SSL_MODE. A variable you set still wins. The host-based defaults use the deploy's own hostname, plus KUBE_INGRESS_ALIAS_DOMAINS in production, so review apps and staging get their own instead of production's.

So a new site sets only what is its own:

• The cluster connection: KUBE_CONTEXT (GitLab agent context), or on GitHub the KUBECONFIG and KUBE_CONTEXT secrets and the KUBE_NAMESPACE_PRODUCTION secret. See Kubernetes and hostnames.
• The domain: KUBE_INGRESS_BASE_DOMAIN.
• The database: DATABASE_URL with CWA_CI_POSTGRES_ENABLED="false". See Database.
• The media bucket: GCLOUD_JSON, GCLOUD_BUCKET and optionally GCLOUD_PUBLIC_URL. See Media storage.
• The mailer: MAILER_DSN and MAILER_EMAIL.
• The first admin: at least ADMIN_PASSWORD. See Application.
• A trusted certificate: CWA_CI_CLUSTER_ISSUER=letsencrypt-prod, once production's domain points at the cluster.
• Recommended for production: the secrets (APP_SECRET, MERCURE_JWT_SECRET and the JWT key pair). They're optional: a deploy keeps the release's live values, and generates them only for a new release.

Deploying a CWA Site walks through these in order.

Naming rules

The variables follow three naming rules:

• CWA_CI_* are the template's own pipeline and deploy switches, such as CWA_CI_STAGING_ENABLED or CWA_CI_PWA_AUTOSCALE_MIN. The sizing of the php pod is CWA_CI_API_*.
• CWA_API_* and NUXT_* are settings the containers read at runtime, passed through by prefix. See Site settings.
• Site values, secrets and names set by the platform keep their own names: DATABASE_URL, POSTGRES_*, APP_SECRET, JWT_*, MERCURE_JWT_SECRET, MAILER_*, GCLOUD_*, ADMIN_*, CORS_ALLOW_ORIGIN, TRUSTED_HOSTS, MERCURE_CORS_ORIGIN, DATABASE_SSL_MODE, CADDY_CACHE_CDN_CONFIG, GITHUB_TOKEN, KUBERNETES_VERSION, HELM_VERSION, and the KUBE_* and CI_* variables.

Kubernetes and hostnames

CWA_CI_CLUSTER_ISSUER defaults to letsencrypt-staging (set by setup.sh), whose certificates browsers don't trust. Set letsencrypt-prod for production once the domain points at the cluster. Until then, a misconfigured domain fails against the staging issuer's much higher limits instead of using up Let's Encrypt's production limits. An empty value turns cert-manager off. Keep the variable on every production site. Both issuers must exist in the cluster under these names (see Deploying a CWA Site).

On GitHub, the workflows' setup actions read vars.KUBERNETES_VERSION and vars.HELM_VERSION. On GitLab, setup.sh sets the defaults only when no CI variable sets them (13243ae).

Secrets

All of them are optional. For each one that isn't a CI variable, deploy_secrets reads the value from the release's live Secret, and generates a new one only when the release doesn't have one yet (#144, 816997e). The JWT key is kept together with its own passphrase, and the public key is derived from them. So logins, signed URLs and Mercure cookies survive a deploy, and pods on either side of a rollout agree. They're passed to Helm with --set, so they win over a project's project_values.

Setting them as protected, masked CI variables (GitHub: secrets) is still worth it for production. A release that is uninstalled, for example with CWA_CI_HELM_UNINSTALL or a stopped review app, loses its Secret, and its next deploy generates new values. A CI variable also lets you rotate a value on purpose.

To rotate a value, set a new one as the CI variable and deploy. Removing the variable doesn't rotate it, because the deploy then keeps the live value. For the JWT key pair, set JWT_SECRET_KEY and JWT_PASSPHRASE, and leave JWT_PUBLIC_KEY empty to have it derived. A new JWT key pair signs every user out when it's deployed, because tokens signed with the old key no longer verify.

The JWT_* values hold the keys' contents, for the deploy. The functional tests job unsets them, so they never reach the tests (see CI/CD → Test).

Application

<hosts> is the deploy's own hostname, plus KUBE_INGRESS_ALIAS_DOMAINS in production, with dots escaped.

Media storage

On GitHub, set GCLOUD_JSON as a secret and the other two as variables.

How long media is cached

From api-components-bundle 2.0.0-alpha.15, every file written to the bucket gets its own Cache-Control. Originals get public, max-age=31536000, immutable, because a stored name is never reused. Image variants get public, max-age=2592000, because a regenerated variant keeps its path. Files stored before then keep GCS's one-hour default until you back-fill them (template 2.0.0-alpha.25's upgrade notes).

Create the CDN's backend bucket with both caps at a year, or raise them on an existing one:

gcloud compute backend-buckets update <backend-bucket> --max-ttl=31536000 --client-ttl=31536000

Changes reach the CDN's edges within a few minutes. Invalidate the CDN host afterwards so files it already holds pick up the new headers: gcloud compute url-maps invalidate-cdn-cache <url-map> --host <cdn host> --path "/*". To check, curl -sI a variant through the CDN: it should send max-age=2592000.

Database

With the in-cluster PostgreSQL (CWA_CI_POSTGRES_ENABLED not "false"), the deploy writes the three POSTGRES_* variables that are set to the chart's postgresql.global.postgresql.auth. Bitnami's subchart creates the database from those values, and the chart builds the API's database-url from them, percent-encoding each part (e15f168). An unset variable keeps the chart's default.

PostgreSQL creates the user and database only when it starts on an empty data directory. Without persistence, changing the user or database name on a live site restarts the PostgreSQL pod empty, so the content has to be loaded again. A new password alone doesn't restart the pod, so the API can't connect until you run kubectl delete pod <release>-postgresql-0, which also starts it empty.

With persistence, the volume keeps the user, password and database it was created with, and a deploy doesn't change them. Change them in PostgreSQL first, as the postgres superuser, with ALTER USER or ALTER DATABASE (renaming a user clears its password, so set it again), then set the new values and deploy.

On GitLab, a POSTGRES_* variable with the All environment scope also reaches the functional tests job, where it replaces the job's own runner/password/test, for both the test database and its URL. Scope these variables to your deploy environments. On GitHub, the deploy jobs don't map them from secrets, so set them as Actions variables; the test job sets its own and ignores them.

In-cluster PostgreSQL persistence

The three CWA_CI_POSTGRES_* persistence variables go to the chart's postgresql.primary.persistence, and only the ones that are set. Unset, the chart's defaults apply: no volume, and standard at 1Gi once it's turned on (7675190).

Kubernetes can't change a StatefulSet's volume once it exists, so Helm would fail part way through. Before anything changes, the deploy compares the variables with the live PostgreSQL and stops when they differ, with the commands to run and what happens to the data. It never deletes anything itself:

A first deploy, with no PostgreSQL yet, can use any settings. If the CI can't read the StatefulSet, the deploy prints a warning and skips the check.

Helm leaves volumes behind when it uninstalls a release. Stopping a review app also deletes its PostgreSQL volume, so a branch deployed again starts with fresh data and credentials. Staging and canary keep theirs: a persistent staging volume outlives delete staging, so delete it by hand with kubectl delete pvc data-<release>-staging-postgresql-0. On GitLab, a CWA_CI_POSTGRES_PERSISTENCE scoped to production reaches staging and canary too.

Composer

setup.sh turns the token into COMPOSER_AUTH and build_api passes that to the build as a secret (see CI/CD → Build). Leave the variable unset rather than empty: an empty token is rejected outright, which is worse than anonymous. GitHub Actions needs nothing: the build step maps the workflow's own secrets.GITHUB_TOKEN (!12).

Autoscaling and sizing

The php pod and the Nuxt pod scale separately. The CWA_CI_API_* variables control php and the CWA_CI_PWA_* variables control Nuxt.

php (API)

CWA_CI_API_AUTOSCALE_MAX is 1 on purpose. The php pod keeps its cache and its Mercure data in memory, so a second pod would not see purges made by the first. See Kubernetes → Autoscaling.

php memory budget

These size the php container's memory (#136, 1868035):

The budget is:

workers × PHP memory limit + (imagine limit − PHP memory limit) + reserved + Go ≤ CWA_CI_API_MEMORY_LIMIT

Go (Caddy, Souin and Mercure) gets what is left, as GOMEMLIMIT: with the defaults, 4 × 128 + 192 + 160 = 864Mi, which leaves Go 160Mi of 1Gi. The imagine limit counts once: the budget allows for one request generating a filter at a time.

The deploy fails before it changes anything in the cluster when the budget leaves Go under 64Mi, or when a value isn't a whole number or an Mi/Gi quantity. The log shows the sum and what to change. With a CWA_CI_API_MEMORY_LIMIT in another form, such as 1G, the check is skipped and GOMEMLIMIT is left unset unless CWA_CI_API_GOMEMLIMIT sets it. So when you raise the workers or the PHP memory limit, raise CWA_CI_API_MEMORY_LIMIT too.

Console commands, such as the orphan scan or a kubectl exec into the pod, don't use FRANKENPHP_MEMORY_LIMIT. They run at the memory_limit of 256M in api/frankenphp/conf.d/10-app.ini.

The template's Image entity accepts uploads up to 30 megapixels: what the 320M imagine limit can thumbnail with the template's libvips driver. If you switch the driver back to GD, lower it to 20 megapixels. See Uploadable.

Nuxt (SSR)

Change CWA_CI_PWA_CPU_REQUEST and CWA_CI_PWA_AUTOSCALE_CPU_PERCENT together. The target is a percentage of the request, and request × target should stay near 175m, about one render a second. See Kubernetes → Nuxt scales out.

The minimums, maximums and memory requests depend on the environment, so review apps and staging don't reserve as much as production. Limits are the same everywhere.

The Nuxt HPA scales on CPU only. Server rendering is CPU-bound, and an extra pod doesn't relieve memory, because each pod keeps its own caches. Node also rarely hands memory back, and an HPA only scales down when every metric is under its target, so a memory target would add pods under normal load and then keep them. Set CWA_CI_PWA_AUTOSCALE_MEMORY_PERCENT if you want one anyway. If you set a variable, your value is used in every environment.

Orphan scan

The daily orphan scan is a CronJob that runs scan-orphaned and emails MAILER_EMAIL when the orphans change.

Staging and canary are off by default because they can share production's database, so their scans would repeat production's alert. Review apps are short-lived.

The email goes to MAILER_EMAIL, the same address the site sends from (orphaned_resources.notify.recipients in api/config/packages/silverback_api_components.yaml). Both a bare address and the Name <address> form work; see Emailing when orphans change.

An empty MAILER_EMAIL means no email. An unset MAILER_DSN renders as null://null, so nothing is sent. The GitHub deploy jobs pass MAILER_DSN (a secret), MAILER_EMAIL and the CWA_CI_ORPHAN_SCAN* variables.

Origin protection

These protect php and Nuxt from requests that get past the cache. Every one is optional: leave it unset, or empty, and the default in api/frankenphp/Caddyfile or worker.Caddyfile applies. On GitHub, set them as Actions variables and they reach the deploy without a workflow change.

The Caddy settings are site settings: set CWA_API_<NAME> in CI and the php container gets <NAME>, so CWA_API_RATE_LIMIT_EVENTS arrives as RATE_LIMIT_EVENTS. The local compose stack uses the bare names (see Docker → Origin protection settings). The CWA_CI_INGRESS_* ones are deploy switches, which the deploy turns into ingress annotations.

See Rate limit on cache misses for what is counted and how the visitor's address is found.

CDN purging

Only needed when a CDN caches your pages. See Cloudflare.

CADDY_CACHE_CDN_CONFIG: setting it replaces the default, so repeat strategy hard. For Cloudflare: strategy hard, provider cloudflare, zone_id <zone ID> and api_key $CLOUDFLARE_API_TOKEN, with no email line. It is stored in the release's Secret.

The CWA_API_CLOUDFLARE_PURGE_* settings reach php as CLOUDFLARE_PURGE_*, like any site setting. Locally, compose passes the bare names through when they're set. CADDY_CACHE_CDN_CONFIG keeps its own name, because the deploy checks it before anything changes.

On GitHub, a variable can't refer to another one. Put the token directly in CADDY_CACHE_CDN_CONFIG, store that as a secret, and map it in the deploy jobs' env:, because the template's workflows don't map it.

On GitLab, scope both variables to production, and protect the token only if the deploy branch is protected: see Cloudflare → Secrets. A deploy fails before rolling anything out if a cdn setting has no value or an unexpanded $NAME.

Image variants

These control generating image variants after a deploy, in one-off Kubernetes Jobs (see Kubernetes → Image Variants Jobs). Since template 2.0.0-alpha.27 · release notes

As with the cache warm, there's one variable per track, because the staging job runs under environment: production. On GitHub, set them as Actions variables.

Cache warm

These control the cache warm after a deploy.

Set these as GitLab CI/CD variables or GitHub repository variables. There's one variable per track, not one environment-scoped variable, because the template's staging deploy job uses environment: production. An environment scope therefore can't tell staging and production apart.

Performance audit

These control the manual performance audit.

Pipeline flags

Site settings

A site's own settings, such as an analytics ID for Nuxt or an API key for a Symfony service, are CI variables. The Kubernetes deploy passes them to the containers by their prefix, so adding one needs no change to k8s.sh, the chart or a workflow (#125, 497e8ac, 75a416b).

The chart adds them to the containers with envFrom (see Kubernetes → Site Settings). The API's settings need the CWA_API_ prefix because its own names, such as DATABASE_URL or APP_SECRET, are too generic to pass through whole.

An empty CWA_API_ value is left out, and the log says so (api: <NAME> left unset, CWA_API_<NAME> is empty). An empty variable would replace the Caddyfile's {$NAME:default} and Symfony's defaults, so leaving it out keeps them. An empty NUXT_* value is still delivered, because Nuxt applies an empty value on purpose.

The API's optional settings

The template's own optional API settings go through the same passthrough. Set them as CWA_API_<NAME> in CI; the local compose stack uses the bare <NAME>. Unset, the default in the Caddyfile or in Symfony applies (d64c278).

Their bare CI names, such as RATE_LIMIT_EVENTS or CLOUDFLARE_PURGE_PLAN, are no longer read by the deploy.

Each side reads them as it reads any environment variable:

• Nuxt uses a NUXT_* variable only for a key you declare in runtimeConfig in app/nuxt.config.ts. NUXT_PUBLIC_ANALYTICS_ID sets runtimeConfig.public.analyticsId, and NUXT_MAPS_KEY sets the server-only runtimeConfig.mapsKey.
• Symfony reads CWA_API_MAPS_KEY as MAPS_KEY, through '%env(MAPS_KEY)%'. Give it a default in api/.env so the local stack still boots.

// app/nuxt.config.ts
export default defineNuxtConfig({
    runtimeConfig: {
        mapsKey: '',          // NUXT_MAPS_KEY, server only
        public: {
            analyticsId: '',  // NUXT_PUBLIC_ANALYTICS_ID, sent to browsers
        },
    },
})

On GitLab, every CI variable already reaches the deploy job. Remember that staging runs under environment: production, so a setting scoped to production reaches staging too. Use the environment name where the two must behave differently.

The deploy log prints Environment name: <name> and one line for each setting, such as pwa config NUXT_PUBLIC_ANALYTICS_ID (from NUXT_PUBLIC_ANALYTICS_ID) or api secret MAPS_KEY (from CWA_API_MAPS_KEY). It never prints a value.

Reserved names

The deploy fails, before it changes anything in the cluster, when a site setting uses a name the chart or its image already sets on that container. The chart's own env: entry would win over envFrom, so the value would be ignored without a word. It also fails on a name that isn't usable, such as CWA_API_ with nothing after it, or a <NAME> that starts with a digit. The log lists every problem:

❌ Site environment variables (NUXT_*, CWA_API_*) that can't be passed through:
  CWA_API_DATABASE_URL: DATABASE_URL is reserved on the api container: the chart or its image sets it (use its own CI variable, if it has one, or delete this one)

Reserved on the Nuxt container (SITE_ENV_RESERVED_PWA in k8s.sh):

NUXT_CWA_API_URL, NUXT_PUBLIC_CWA_API_URL, NUXT_PUBLIC_CWA_API_URL_BROWSER, NUXT_SITE_URL and NUXT_PUBLIC_CWA_ENVIRONMENT. The deploy sets NUXT_SITE_URL to https://$DOMAIN, so cached pages' canonical URL and og:url use the site's own host, not whichever host rendered the page. A multi-site project gives each site its host through DOMAIN (#140, 45a3794). The chart sets the API URLs itself (see Kubernetes → apiUrl should stay unset). NUXT_PUBLIC_CWA_API_URL is the deprecated name of NUXT_CWA_API_URL, and as public config it would put the internal API URL in every page.

Reserved on the php container (SITE_ENV_RESERVED_API), as the <NAME> in CWA_API_<NAME>:

ADMIN_EMAIL, ADMIN_PASSWORD, ADMIN_USERNAME, APP_DEBUG, APP_ENV, APP_SECRET, APP_UPSTREAM, BROWSER_SERVER_NAME, CACHE_URL, CADDY_CACHE_CDN_CONFIG, CADDY_CACHE_EXTRA_CONFIG, CORS_ALLOW_ORIGIN, CWA_ENVIRONMENT, DATABASE_CA_CERT, DATABASE_CLIENT_CERT, DATABASE_CLIENT_KEY, DATABASE_SSL_MODE, DATABASE_URL, FRANKENPHP_CONFIG, FRANKENPHP_MEMORY_LIMIT, FRANKENPHP_WORKER_NUM, GCLOUD_BUCKET, GCLOUD_JSON, GCLOUD_PUBLIC_URL, GOMEMLIMIT, JWT_PASSPHRASE, JWT_PUBLIC_KEY, JWT_SECRET_KEY, MAILER_DSN, MAILER_EMAIL, MERCURE_CORS_ORIGIN, MERCURE_EXTRA_DIRECTIVES, MERCURE_JWT_SECRET, MERCURE_PUBLIC_URL, MERCURE_PUBLISHER_JWT_ALG, MERCURE_PUBLISHER_JWT_KEY, MERCURE_SUBSCRIBER_JWT_ALG, MERCURE_SUBSCRIBER_JWT_KEY, MERCURE_URL, RESET_DATABASE, SERVER_NAME, TRUSTED_HOSTS and TRUSTED_PROXIES.

Most of these have their own CI variable, such as MAILER_DSN or CORS_ALLOW_ORIGIN (or CWA_CI_API_GOMEMLIMIT for GOMEMLIMIT, CWA_CI_API_WORKERS for FRANKENPHP_WORKER_NUM, CWA_CI_API_PHP_MEMORY_LIMIT for FRANKENPHP_MEMORY_LIMIT, and CWA_CI_RESET_DATABASE for RESET_DATABASE), so set that one instead.

If your own chart values add env: entries to a container, reserve their names too, without editing k8s.sh: set SITE_ENV_RESERVED_API_EXTRA or SITE_ENV_RESERVED_PWA_EXTRA to a space-separated list in project.sh or as a CI variable (#133).

export SITE_ENV_RESERVED_API_EXTRA="MAPS_REGION"

On GitHub

Variables named NUXT_* or CWA_API_* reach the deploy through github-export-vars.sh, like every other variable. GitHub can't list secrets, so each deploy job (review, staging, canary and production) also runs bin/devops/github-export-secrets.sh, in the step Expose NUXT_* and CWA_API_* secrets to the deploy. It receives every secret and exports only the NUXT_* and CWA_API_* ones to the later steps, masked, including each line of a multi-line value. It runs after the kubectl and Helm setup actions, so those never see the values, and no build job runs it. So a site secret needs no workflow edit: add it under Settings → Secrets and variables → Actions → Secrets.

The step adds a warning to the run in two cases:

• Public value stored as a secret: a NUXT_PUBLIC_* secret. It is still exported, but browsers receive it, so make it a variable.
• Secret shadowed: a variable, or the job's env:, already sets the name, so the secret isn't used. Delete one of the two.

The environment name

The deploy names the environment it serves, from its track, and sets it as CWA_ENVIRONMENT on the php pod and the orphan scan, and as NUXT_PUBLIC_CWA_ENVIRONMENT on the Nuxt pods (Helm value cwaEnvironment):

So staging is told apart from production, although its GitLab job runs as environment: production. A CWA_ENVIRONMENT CI variable replaces the name on every track it reaches; on GitLab, a value scoped to production reaches staging and canary too. It may hold only letters, digits, ., _ and -, or the deploy fails with CWA_ENVIRONMENT must be letters, digits, '.', '_' or '-', not '<value>'.

Nuxt sees the name only once you declare it, as runtimeConfig.public.cwaEnvironment. Symfony reads it with '%env(CWA_ENVIRONMENT)%'; give it a default in api/.env for the local stack.