CI/CD

The template ships complete CI/CD for both GitLab CI and GitHub Actions. Every step delegates to shell functions in bin/devops/ — readable, modifiable scripts you own.

Choose your CI/CD provider when you run pnpm create cwa — the CLI wires up the correct pipeline files automatically. You can switch later by copying the relevant files from the template.

GitHub Actions

Three workflows drive your app, in .github/workflows/:

The template repo also has publish-create-cwa.yml, which publishes the scaffolding CLI. create-cwa leaves it out of new projects; if an older project has it, it is safe to delete.

Images push to GHCR (ghcr.io/${{ github.repository }}). The workflows call the same bin/devops/ shell functions as GitLab CI. Required secrets and variables are declared in the workflow files themselves, and listed under Required CI/CD Variables below.

GitLab CI

The .gitlab-ci.yml has seven stages: build, test, review, staging, canary, production and cleanup. There is no GitLab Auto DevOps magic here.

GitLab runs branch pipelines only. The workflow creates no merge request pipelines, because every job is limited to branches. A merge request shows its branch pipeline's result, so Pipelines must succeed works as expected.

Pipeline Overview

On every branch: build then test then spin up a review app on Kubernetes. When a branch merges to main: build and test run again, then the pipeline auto-deploys to staging, from where you manually promote through canary to production.

Stages

Build

Two parallel jobs — build api and build app — each run docker buildx and push to the GitLab Container Registry. Layer caching is handled with --cache-to / --cache-from against a dedicated cache image tag, so incremental builds are fast.

$CI_REGISTRY_IMAGE/php:$CI_COMMIT_REF_SLUG    ← FrankenPHP image (--target frankenphp_prod)
$CI_REGISTRY_IMAGE/app:$CI_COMMIT_REF_SLUG    ← Nuxt image       (--target prod)

The PHP image build uses api/Dockerfile; the Nuxt image uses app/Dockerfile. Build logic lives in build_api() and build_app() in bin/devops/k8s.sh.

Test

Two parallel jobs against the image built in the previous stage:

Both export JUnit XML for GitLab's test report UI.

Review Apps

A branch (other than main) gets a review app, with its own Helm release, only once someone creates its Kubernetes namespace. The pipeline never creates namespaces. The URL follows the pattern https://$CI_COMMIT_REF_SLUG-review.$KUBE_INGRESS_BASE_DOMAIN.

The review job checks for the namespace first (skip_review_without_namespace):

The jobs that follow a review (the review fixture load, cache warm, performance audit and stop jobs) start with skip_unless_review_deployed. When the review job didn't deploy, they exit with code 3 and say why, instead of running against an environment that doesn't exist. Projects created before the template's 2.0.0-alpha.2 release don't have this guard.

An orange pipeline on a branch just means that branch has no review app. A deploy that really fails is still red. Staging, canary and production don't make this check: a missing namespace there fails the job.

Creating a namespace for a branch

1. Find the name. The job log prints it: No namespace '<name>', so this branch has no review environment to deploy to. It is KUBE_NAMESPACE, which defaults to <project name>-<environment slug>. On GitHub that is <repository name>-review-<branch slug>. On GitLab the slug is GitLab's CI_ENVIRONMENT_SLUG for review/<branch>, which GitLab shortens and may give a random suffix, so copy the name from the log.
2. Create the namespace, and bind the identity your CI deploys with to a role in it. For example, with the built-in edit role:

   kubectl create namespace <name>
   kubectl create rolebinding ci-deploy --namespace <name> \
     --clusterrole=edit --serviceaccount=<ci-namespace>:<ci-service-account>
   

   
   Which identity and role you need depends on your cluster and on how the CI connects (the GitLab agent, or the KUBECONFIG secret on GitHub). Give it the same access as your other environments.
3. Run the review job again.

A namespace that exists without the role bindings still shows orange, because the CI is forbidden to read it.

Review apps are torn down manually via the stop review job (triggered from the GitLab environment list), or automatically when the branch is deleted. Stopping one uninstalls its Helm release but leaves the namespace, so delete the namespace by hand once the branch is gone.

Staging

Runs automatically on every merge to main (controlled by $STAGING_ENABLED, default "true"). Calls deploy staging which runs helm upgrade --install for a separate -staging release. Staging runs under the production environment, so it deploys into production's namespace and gets production's variables.

Canary

A manual job that runs deploy canary. Useful for routing a portion of production traffic to the new image before full rollout. Enable/disable via $CANARY_ENABLED.

Like production, it waits for the builds and tests (see Production below).

Production

A manual job requiring explicit trigger from GitLab. Calls deploy (stable track), then delete canary and delete staging to clean up the intermediate environments.

Production and canary can't start until build api, build app, unit tests and behat tests have passed, and staging too when it is enabled. Each of these needs is optional, so BUILD_DISABLED and TEST_DISABLED still work.

The Devops Scripts

All CI logic lives in two scripts sourced at the top of every job:

bin/devops/setup.sh

Sets shared environment variables:

• CI_APPLICATION_REPOSITORY / CI_APPLICATION_TAG — image repo and SHA tag
• PHP_REPOSITORY / APP_REPOSITORY — full image paths
• PHP_REPOSITORY_CACHE / APP_REPOSITORY_CACHE — layer cache image paths
• DOMAIN — derived from CI_ENVIRONMENT_URL
• DEPLOYMENT_BRANCH — defaults to main

bin/devops/k8s.sh

Contains all the functions the pipeline calls:

Why every deploy clears the page cache

Cached pages link to the JavaScript and CSS files of the build that rendered them. A new front-end build gives those files new names and deletes the old ones. Without a purge, the cache keeps serving pages that point at files that no longer exist, so visitors see an unstyled page that does not work until the cached copy expires, which can take up to an hour.

purge_rendered_html prevents this. It waits until the new Nuxt pods have fully replaced the old ones, because an old pod could otherwise put an old page back into the cache. Then it runs php bin/console silverback:api-components:purge-rendered-html in the php pod. That command clears only the rendered pages, which share the cwa-html cache tag, and leaves cached API responses alone. It uses the pipeline's existing kubectl access, so it needs no extra credentials. If a site has no HTTP cache configured, the command does nothing and still succeeds.

Warming the cache after a deploy

A purge leaves the cache empty, so the first visitor to each page would wait for a server render. warm_cache fills it again, as its own job after a deploy: warm cache review, warm cache staging, warm cache canary and warm cache production on GitLab, and a Warm the page cache step on GitHub, after the fixtures step so a new environment is warmed once its content exists. Only production is warmed by default; the other tracks opt in (see the table below). The production deploy never waits for a warm job. It reads /sitemap.xml from the environment URL (following one level of sitemap index), then requests every page anonymously, three at a time by default, and prints each page's status and time to first byte.

Any page that doesn't return 200 is listed under a CACHE WARM FAILED banner, and on GitHub it also raises an ::error annotation on the run summary. The warm job fails, but it is allowed to (allow_failure: true on GitLab, continue-on-error: true on GitHub), so the pipeline shows a warning instead of a failed deploy. By then the new release is already live, and the deploy and its cleanup steps have already run. Read the warm job's log when it warns.

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.

Auditing performance after a deploy

warm_cache tells you how quickly the server answered. performance_audit tells you what a visitor experiences. It runs Lighthouse CI (@lhci/cli) against a few pages and reports LCP, CLS, TBT, FCP, Speed Index and page weight. Run it after the cache warm, so it measures cached pages, which is what visitors get. Each page is loaded anonymously with no query string, so the audit neither bypasses nor splits the cache.

The audit is manual. It is available by default, but it never runs by itself.

• GitLab: after a deploy, press play on the performance audit review, performance audit staging or performance audit production job. Each one waits for its deploy job, and for its warm job when warming is on. Set PERFORMANCE_AUDIT_REVIEW, PERFORMANCE_AUDIT_STAGING or PERFORMANCE_AUDIT_PRODUCTION to "false" to remove that job. performance audit canary is opt-in (PERFORMANCE_AUDIT_CANARY="true"), because canary shares production's hostname and would measure whichever pod answers.
• GitHub Actions: run the Performance audit workflow (performance-audit.yml) from the Actions tab. Choose the environment (production, staging or review) and the form factors. For a review app, run the workflow from that branch, because the URL is built from the branch name. Set a repository variable PERFORMANCE_AUDIT_PRODUCTION, PERFORMANCE_AUDIT_STAGING or PERFORMANCE_AUDIT_REVIEW to "false" to disable that environment.

By default it audits the first three pages of /sitemap.xml, on mobile, five runs each. That is 15 page loads. Five runs stop one slow run on a shared CI runner from changing the median. Pages are audited one after another, never in parallel, because parallel runs share the runner's CPU and network and skew every metric.

The audit uses real throttling (Lighthouse's devtools method) by default. Lighthouse's simulated throttling gave very different scores for the same page on shared CI runners, from 0.60 to 0.96. Only the performance category is collected.

Budgets

The budgets are in bin/devops/lighthouserc.json. They use Lighthouse's "good" thresholds:

To change them, edit bin/devops/lighthouserc.json, or point PERFORMANCE_AUDIT_CONFIG at your own file.

A missed error budget fails the audit, but it never fails a deploy. On GitLab the job is allowed to fail, so the pipeline shows "passed with warnings". On GitHub the audit run fails with a warning. That run is only the audit, and the deploy has already finished.

Reading the results

The reports go in performance-report/: Lighthouse's HTML and JSON for each page and form factor, the budget results, and a summary.md table.

The end of the job log shows the same results as an aligned text table. It has one row per page and form factor, from the median run. The columns are Page, Device, Score, LCP, FCP, TBT, CLS, Speed Index and Weight. Each value with a budget is marked:

• ✓ within budget
• ✗ over an error budget, which fails the audit
• ⚠ over a warning budget

The marks are read from the budgets in lighthouserc.json, so they match what failed the audit.

• GitLab: download the job's performance-report/ artifact, kept for 30 days. The job also writes a browser_performance report. GitLab uses it to compare metrics between pipelines in the merge request, but that widget needs GitLab Premium. On Free, you still get the artifact.
• GitHub Actions: the table is in the workflow run's summary. The full reports are in the performance-report-<environment> artifact, kept for 30 days.

Required CI/CD Variables

Set these in Settings → CI/CD → Variables in GitLab. Variables marked auto-generated are created by generate_jwt_keys() at pipeline start if not set — useful for review apps, but for production you should pin them as CI secrets so they don't rotate on every deploy.

Kubernetes

JWT & Mercure

For production, generate these once and save them as protected, masked CI variables. Otherwise they regenerate on every deploy, invalidating all active user sessions.

Before template 2.0.0-alpha.3 (85d3f43), a supplied JWT_SECRET_KEY without JWT_PASSPHRASE got a random passphrase that could never decrypt it, and JWT_PUBLIC_KEY was never derived. Login then failed at runtime instead of the deploy failing.

Application

Media Storage

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

Database

Autoscaling

The php pod and the Nuxt pod scale separately. The AUTOSCALE_* variables control php and the PWA_* variables control Nuxt.

php (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.

Nuxt (SSR):

The minimums, maximums and 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 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 from bundle 2.0.0-alpha.7. On 2.0.0-alpha.6, use a bare address; 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 ORPHAN_SCAN* variables.

Pipeline Flags

Fixtures seed a new environment: the scaffold pages and the first admin user. They are off unless ENABLE_DATABASE_FIXTURES is "true".

• GitLab: a load fixtures job appears for review apps and for production, after the deploy job. It never runs automatically; trigger it from the pipeline UI.
• GitHub Actions: a Load fixtures step runs after each review deploy, and after a manual production run, while the variable is "true". GitHub has no manual jobs inside a push-triggered workflow, so set the variable for a new environment's first deploy, then remove it.

Staging has no fixture job on either. It runs under the production environment, so with an external database (DATABASE_URL) it uses production's database, and a fixture load there would write to production.

By default load_fixtures runs doctrine:fixtures:load --append, so it never deletes existing content. The admin user fixture can be run any number of times. What the scaffold does on a database that already has content depends on the bundle version:

• From bundle 2.0.0-alpha.5 (the template pins 2.0.0-alpha.6), appending creates only what is missing and keeps existing content. See Appending to an Existing Site.
• Up to bundle 2.0.0-alpha.4, the scaffold stops at the first page route that already exists. Nothing is written, and the step reports a failure, which is allowed so it does not fail the deploy.

After a successful load, load_fixtures flushes the whole HTTP cache (silverback:api-components:purge-http-cache), API responses and pages alike. The load changes the database underneath what Souin has cached since the deploy, and nothing else would purge it, so production could otherwise serve the old content for up to a year.

Purging before a load

FIXTURES_PURGE is for an early project whose database should be rebuilt from a changed scaffold. It runs doctrine:fixtures:load without --append, which empties every table first.

Only the fixture job reads it. A deploy or a pod restart never purges.

On GitHub, staging also only runs when the STAGING_ENABLED variable is set to true. ci.yml has no default for it.

Changing a live site's hostnames

Production's certificate covers its main hostname and every entry in KUBE_INGRESS_ALIAS_DOMAINS. You change that list when you launch a site, add www, or retire the preview hostname. To do it, edit the variables and deploy:

• Add a hostname: add it to KUBE_INGRESS_ALIAS_DOMAINS.
• Retire a hostname, such as the preview host: remove it from KUBE_INGRESS_ALIAS_DOMAINS. It then goes offline. The template has no redirect feature, by design.
• Change the main hostname at launch, for example new.example.org → example.org: the main hostname is the production environment URL, https://$KUBE_INGRESS_BASE_DOMAIN, so change KUBE_INGRESS_BASE_DOMAIN. Staging and review apps are subdomains of it, so they move too. Keep the old host in KUBE_INGRESS_ALIAS_DOMAINS if it should still work.

When the list differs from the live certificate's, the deploy creates a new cert-manager Certificate for the new list. It waits until the certificate is issued, for up to TLS_CERTIFICATE_TIMEOUT (default 600s), and only then runs Helm. The ingress moves from one valid certificate to another, with no downtime. When the list is unchanged, which is almost every deploy, the deploy keeps the live certificate and nothing is reissued. The order and case of the hostnames don't matter.

Some details:

• The deploy compares against the certificate on the chart's own ingress, which it finds by the release name. This is why changing the main hostname at launch is still safe.
• Other ingresses in the namespace are ignored, even with the same chart labels. For example, a redirect ingress you added by hand for a retired hostname keeps its own certificate. The deploy doesn't compare against it or remove it.
• New certificates are named <LETSENCRYPT_SECRET_NAME>-stable-api-<hash>, from a hash of the hostname list. After a successful deploy, older ones created this way are deleted, with their secrets. The one just replaced is kept, so a rollback still has a valid certificate. You no longer change LETSENCRYPT_SECRET_NAME by hand.
• Only production (the stable track) is covered. Review, staging and canary each serve one hostname that doesn't change. The first deploy of a release also works as before, because nothing is live yet.

Permissions

The CI service account needs access to certificates.cert-manager.io in the namespace. The deploy creates, patches, gets, watches, lists and deletes Certificates, and deletes the secrets of the ones it removes. It checks only create up front. Without it, the deploy prints a warning and falls back to changing the live certificate in place, which causes the downtime described above.

Changing hostnames by hand

Use this if the CI account can't manage Certificates, or your pipeline doesn't have ensure_tls_certificate.

1. Choose a new value for LETSENCRYPT_SECRET_NAME, for example letsencrypt-cert-2. The production ingress uses the secret <LETSENCRYPT_SECRET_NAME>-stable-api.
2. Apply a Certificate that writes that secret and covers the new hostnames:

   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: letsencrypt-cert-2-stable-api
   spec:
     secretName: letsencrypt-cert-2-stable-api
     issuerRef:
       group: cert-manager.io
       kind: ClusterIssuer
       name: letsencrypt-prod # your CLUSTER_ISSUER
     dnsNames:
       - example.org
       - www.example.org
   

3. Wait until it is ready: kubectl wait --for=condition=Ready certificate/letsencrypt-cert-2-stable-api -n <namespace> --timeout=600s.
4. Set LETSENCRYPT_SECRET_NAME to the new value, update the hostname variables, and deploy.
5. Keep the old Certificate and secret until the site works on the new one. Then delete them.

Rollback

# List Helm history
helm history cwa --namespace production

# Roll back to a specific revision
helm rollback cwa 3 --namespace production

# Roll back to the previous release
helm rollback cwa --namespace production

Helm's rollback restores the previous release's values, image tag included. The template's pipeline tags images with the branch slug ($CI_COMMIT_REF_SLUG, so main for production), not the commit SHA, and deploys with pullPolicy: Always. The previous release therefore points at the same tag, and a rollback pulls whatever image that tag currently holds. To roll the code back as well, tag images with the commit SHA (CI_APPLICATION_TAG in setup.sh) and deploy that tag.