One pipeline for every app, pinned to a release.

Every uBixCore app needs the same pipeline: build the images, run the checks, migrate the database, deploy per environment, promote the branch, and say so when it fails. Copied into each repository, that pipeline drifts, and a fix has to be made again in every copy.

So the pipeline lives in uBixCore, in ci/ubixcore-pipeline.yml. The deploy, promote and notify scripts live there too, in ci/bin. A host repository includes the template and states only its differences. Upgrading is a version bump, not a merge.

Pin ref to a release tag, never main. Keep it in step with the ubixsys/ubixcore version in composer.lock: the template also fetches ci/bin at that locked version, so the scripts always match the framework the image was built with. The skeleton marks the line ubixcore-ref so a tool can find it.

To upgrade, run composer update ubixsys/ubixcore, bump ref, and commit both.

The shared scripts ship from 0.47.0. On an older locked version the jobs stop with a message telling you to update, or to point UBIX_DEPLOY_SCRIPT, UBIX_PROMOTE_SCRIPT and UBIX_NOTIFY_SCRIPT at your own.

Pipelines run for merge requests, for schedules (maintenance jobs only) and for pushes to the dev, staging and production branches. A push to a feature branch runs nothing: its checks belong to the merge request.

build → test → migrate → deploy → promote → notify
                                              approval  (merge requests)
                                              maintenance  (schedules)

dev push      build → test → migrate → deploy-dev      → promote-to-staging
staging push  build → test → migrate → deploy-staging  → promote-to-prod
main push     build → test → migrate → deploy-prod     (manual by default)
merge request build-mr → static-checks-mr, phpunit-mr, ai-review-mr → require-approval-mr

Promotion is a fast-forward of the next branch, so what reached production is the commit that went green on the tiers before it.

<tier> is dev, staging or prod. Each tier's jobs exist only while that tier is in UBIX_TIERS.

Every job retries twice on infrastructure failures (runner, timeout, API) so a hiccup never needs a click; a genuine failure stays red. Jobs are interruptible so a superseded pipeline frees its runner, except migrate, deploy, promote and notify: half a deploy is worse than a slow one.

Everything a host tunes is a UBIX_* variable, declared with its default at the top of the template. Set it in your variables: or in the project's CI/CD settings; project settings win.

1. Set a variable. Almost everything above is a one-line change.
2. Change a job. Redefine it by name. Keys merge and script replaces: phpunit-dev: { variables: { MY_FLAG: "1" } }.
3. Drop a job. ai-review-mr: { rules: [{ when: never }] }.
4. Add a job. Extend a hidden base, which is public API. .ubix_static_checks, .ubix_phpunit, .ubix_migrate, .ubix_deploy and .ubix_maintenance are the job bodies; .ubix_on_dev, .ubix_on_staging, .ubix_on_prod and .ubix_on_mr pick the tier and its rules.
5. Bring your own script. Point UBIX_DEPLOY_SCRIPT, UBIX_PROMOTE_SCRIPT or UBIX_NOTIFY_SCRIPT at your own. A host with no staging tier defines its own promote job.

The template holds no credentials. A first green pipeline needs:

1. A runner carrying the shell tag (or your own tags), with Docker and a buildx builder, and cluster credentials for the deploy and promote jobs.
2. Image files and manifests: the Dockerfiles named above, and per-app manifests named for the branch, such as app/<App>/dev-deploy.yaml.
3. A uBixVault tree under secret/<prefix>/: test-db, db-<tier>, composer and discord. The jobs read it with read-only tokens held in the masked CI variables UBIXVAULT_CI_TOKEN_DEV and UBIXVAULT_CI_TOKEN_PROD. ci/bin/vault-set-key.sh writes a single key safely.
4. A token for promote: GITLAB_PROMOTE_TOKEN, a project access token that can push the tier branches.
5. A token for the sign-off: APPROVAL_GITLAB_TOKEN (or AI_REVIEW_GITLAB_TOKEN), Reporter with api, masked and not protected, since merge-request branches are unprotected.
6. Optionally, GEMINI_API_KEY and AI_REVIEW_GITLAB_TOKEN for ai-review-mr, masked and not protected for the same reason.
7. Access to uBixCore: your project on uBixCore's job-token allowlist, because the template clones ci/bin with the job token.

The skeleton's docs/ci-setup.md lists each of these in the order to create them, and bin/vault-ci-setup.sh creates the vault policy, the secrets and the CI token in one go.