Pillars pipeline configuration reference

ReferencePublicInterface: GitLab CI/CD

Use this reference to configure Pillars in your application project. You do not need to inspect the Pillars implementation repository. The following pages describe the settings, prerequisites, job behavior, outputs, and limitations of the documented pipeline configuration.

Configuration area	Reference
Workflow, framework selection, containers, and shared credentials	This page
npm, Gradle, pip, Poetry, Go, CMake, and .NET	Framework jobs and configuration
Source analysis, image analysis, browser tests, and scanner thresholds	Analysis jobs and configuration
Helm, Kustomize, Zarf, releases, and evidence archives	Delivery and release configuration
Exact declared defaults, including images and report paths	Variable defaults
Missing jobs, failed checks, access, and artifacts	Troubleshoot Pillars

Defaults describe the documented configuration, not every installation's overrides. Your platform team supplies the approved template revision and any installation-specific settings. Keep that revision with the pipeline record when reporting a problem.

Connect your project

Use the include supplied with your installation. Keep a working include already present in your project. A new installation must supply its template location and approved ref; the example below uses placeholders and is not a universal SmoothGlue repository address.

Replace your-org/pillars-template and APPROVED_REF with those supplied values:

include:
  - project: "your-org/pillars-template"
    ref: "APPROVED_REF"
    file: "pipeline/pipeline.yaml"

The template must be accessible when GitLab creates the pipeline. For an ordinary private include:project, the person running the pipeline needs permission to read the included project. If customers cannot access the implementation repository, the platform team must provide an accessible maintained template or another configured delivery mechanism. A variable or job token set inside a job cannot fix an include that fails before jobs exist. See GitLab's include rules.

Set configuration values

Put non-secret job settings in the top-level variables block of your project's .gitlab-ci.yml. Quote boolean-like values as "true" and "false". Set passwords, API keys, and tokens in Settings > CI/CD > Variables, with masking and protection appropriate to the branches that need them. Protected variables are unavailable to jobs on refs that do not qualify for that protection.

GitLab applies its variable precedence rules. Job-level YAML defaults take precedence over top-level YAML defaults; project, group, and pipeline variables can override YAML values. For a setting declared inside a job, override that named job's variables map or use an appropriately scoped CI/CD variable. For example:

grype:
  variables:
    GRYPE_FAIL_ON_SEVERITY: "critical"

This changes that scanner's threshold; it does not change other scanners or establish an approved exception policy. Preserve the included job's script, rules, and artifact configuration unless you intentionally need to replace their behavior. Lists such as rules, script, and needs are replaced when overridden, not appended. See GitLab variable precedence.

Framework switches used by include:rules must be available before YAML files merge. Set NPM, GRADLE, PIP, POETRY, GOLANG, CPP, DOTNET, HELM, and KUSTOMIZE overrides in project/group CI/CD variables, or another permitted pipeline-creation variable source. The same applies to KUSTOMIZE_PROJECT, KUSTOMIZE_BRANCH, HELM_PROJECT, and HELM_BRANCH when selecting downstream includes. Top-level YAML defaults and job variables cannot control those includes. See variables available to includes. A dotenv artifact also cannot enable an include or job already evaluated for that pipeline. Start a new pipeline after changing the template ref or configuration; retrying an existing job reuses that pipeline's configuration.

Pipeline creation

The workflow evaluates these conditions in order:

Condition	Result
Commit has a tag	Create a pipeline.
Pipeline source is anything other than push	Create a pipeline, including merge-request, manual, scheduled, and downstream sources.
Branch push has an open merge request	Suppress the duplicate branch pipeline.
Branch push contains differences from the default branch	Create a pipeline.
Branch is the default branch	Create a pipeline.
No condition matches	Do not create a pipeline.

Creating a pipeline does not select every job. File detection, switches, and job rules still apply. A new branch identical to the default branch can therefore have no push pipeline, while its merge-request pipeline is permitted.

The stage order is dependencies, code-build, code-analyze, artifact-build, artifact-analyze, publish, evidence, deploy, sync, and release. Jobs with needs can run according to their dependency graph rather than waiting for all earlier stages. Common source-analysis jobs use needs: [] and can start early. The shared pipeline supplies a deploy stage but does not automatically deploy every application to a cluster.

Framework selection

For each framework switch, "false" prevents inclusion, "true" explicitly includes it, and an unset value uses file detection. Selection does not create missing lockfiles, project configuration, credentials, or services.

Integration	Switch	Automatic selection and required project setup
npm	NPM	Root package-lock.json; provide the matching package.json.
Gradle	GRADLE	Root build.gradle selects shared configuration and build support. Analysis and publication includes also match nested build.gradle. Jobs run at the root; nested discovery alone is not multi-project orchestration.
pip	PIP	Root requirements.txt, unless root poetry.lock exists. Packaging additionally requires a PEP 621 pyproject.toml. Explicit PIP: "true" is evaluated before the Poetry exclusion.
Poetry	POETRY	Root poetry.lock; provide the matching pyproject.toml.
Go	GOLANG	Root or nested go.mod; set GO_MODULE_DIR for a nested module.
CMake	CPP	Root or nested CMakeLists.txt; set CMAKE_SOURCE_DIR when several projects exist.
.NET	DOTNET	Root or nested .sln, .slnx, or .csproj; set DOTNET_PROJECT to select a specific target.
Helm	HELM	Chart detection includes the Helm jobs; helm-chart also requires HELM_CHART_DIR/Chart.yaml. Set HELM: "true" with a custom chart directory to remove ambiguity in include detection.
Kustomize	KUSTOMIZE	Matching **/kustomization.yaml; downstream publication is also included when its target project and branch are set.
Zarf	ZARF	Definition detection on tags and the default branch. Explicit "true" also enables other pipeline contexts; see Zarf selection.

When a lockfile exists only for tooling, add a project CI/CD variable with key NPM and value false. This prevents the npm framework includes from being selected.

Multiple frameworks can be selected together, but they share names such as BUILD_DIR, PACKAGE_VERSION, BUILD_ARGS, BUILD_SECRETS, and the release preset. This is not an automatic build matrix. Use explicit job-level choices and verify the resulting job configuration for a mixed-language project.

Job selection and failure behavior

A job switch usually disables a selected job when set to "false". Setting it to "true" does not generally bypass file checks, tag conditions, or dependencies. The framework and analysis references list the switch for each job.

Job family	Default failure behavior
Framework dependency and code-build jobs	Blocking when selected.
Common source-analysis jobs	Use the ordered context rules below.
Container build and most image-analysis jobs	Require the configured Dockerfile and use the context rules below.
Helm chart build	Requires the configured chart and uses the context rules below.
Language package publication	Manual, nonblocking jobs on tags. Several build jobs already publish to staging before this stage.
OpenSCAP	Selected Dockerfile jobs use a rule that permits failure. Do not assume its separate exit-code setting makes other exits blocking.
Zarf build, scan, and publication	Blocking when selected; the scan is omitted if GRYPE: "false".

Context rules match in this order: an upstream merge-request pipeline blocks failures; an explicitly unprotected upstream branch permits failures; the current merge-request pipeline blocks failures; a protected current ref blocks failures; other contexts permit failures. UPSTREAM_PIPELINE_SOURCE, UPSTREAM_COMMIT_BRANCH, and UPSTREAM_COMMIT_REF_PROTECTED describe forwarded context when supplied by the calling pipeline. Leave them unset for an ordinary standalone project.

Required dependencies matter when disabling jobs. For example, sonarqube requires dependency-check, and zap and cypress require both container-image and crane. Disabling the prerequisite alone can make pipeline creation fail. Disable or deliberately reconfigure the dependent jobs as well; see dependency troubleshooting.

Artifacts and analysis

Container image builds

container-image runs in artifact-build when the file at DOCKERFILE_PATH exists, unless CONTAINER_IMAGE: "false". It builds from the repository-root context using Buildah and pushes the primary and additional tags before image analysis starts.

Setting	Default	Meaning
DOCKERFILE_PATH	Dockerfile	Selection path used by Dockerfile-dependent job rules.
DOCKERFILE	Dockerfile	File passed to Buildah; set consistently with the selection path.
REGISTRY	${CI_REGISTRY}	Destination registry hostname, optionally including a port.
IMAGE	Empty	Resolves to the lowercased ${CI_PROJECT_PATH}.
IMAGE_TAG	Empty	Resolution order: explicit tag, PACKAGE_VERSION, commit tag, pipeline ID.
IMAGE_ADDITIONAL_TAGS	${CI_COMMIT_REF_SLUG},${CI_PIPELINE_ID},${CI_COMMIT_SHA}	Comma-separated additional tags. When PACKAGE_VERSION supplies the primary tag on a tag pipeline, the commit tag is added too.
BUILD_ARGS	Empty in the common container configuration	Newline-separated NAME=value entries written to a Buildah argument file. Python framework includes also supply VERSION=${PACKAGE_VERSION}.
BUILD_SECRETS	CI job-token secret mount in the common configuration	Buildah --secret arguments; Python frameworks add package-credential mounts.
CACHE_ARGS	Unset	Additional command arguments passed to Buildah.
CACHE_ENABLED	"true"	Declared but not read by the current build script; setting it to false does not disable caching.
BRANCH_TAG	${CI_COMMIT_REF_SLUG} in the build job	Declared but not used for tag selection by the current script. Use IMAGE_ADDITIONAL_TAGS.

The build always passes --layers, --cache-from, and --cache-to, using REGISTRY/IMAGE/cache. It also writes image.env with REGISTRY, IMAGE, and IMAGE_TAG, and saves an image archive in the container-image-cache GitLab cache. A cache is not durable release storage. Registry presence alone does not mean the image passed its checks.

For a non-root Dockerfile, configure the shared selection path, Buildah input, and the Dockerfile lint job's local default:

variables:
  DOCKERFILE_PATH: "containers/Dockerfile"
  DOCKERFILE: "containers/Dockerfile"

dockerfile-lint:
  variables:
    DOCKERFILE_PATH: "containers/Dockerfile"

Registry authentication

Settings	Default and use
REGISTRY_USER, REGISTRY_PASSWORD	GitLab's ${CI_REGISTRY_USER} and ${CI_REGISTRY_PASSWORD}; used for pushes and image scanning.
UPSTREAM_REGISTRY, UPSTREAM_REGISTRY_USER, UPSTREAM_REGISTRY_PASSWORD	Empty; configure when builds pull from another authenticated registry.
DOCKER_AUTH_CONFIG	Authentication JSON for the container, upstream, and Helm registries. A replacement must contain all registry entries needed by the selected jobs.

Registry access for pulling the job image must be available to the runner before its script starts. Setting credentials during a job cannot repair a failed job-image pull. Keep the separate registry variables populated when using NeuVector; its API request does not obtain credentials from DOCKER_AUTH_CONFIG.

Package registries and directories

Settings	Default and use
PACKAGE_HOST	${CI_SERVER_HOST}; release package host.
STAGING_PACKAGE_HOST	${CI_SERVER_HOST}; development package host.
UPSTREAM_PACKAGE_HOST	Empty; dependency host. Individual frameworks can supply another fallback.
PACKAGE_USERNAME, PACKAGE_PASSWORD	Empty; release credentials where supported by the framework.
STAGING_PACKAGE_USERNAME, STAGING_PACKAGE_PASSWORD	Empty; staging credentials where supported.
UPSTREAM_PACKAGE_USERNAME, UPSTREAM_PACKAGE_PASSWORD, UPSTREAM_PACKAGE_TOKEN	Empty; dependency credentials.
PACKAGE_TOKEN, STAGING_PACKAGE_TOKEN	${CI_JOB_TOKEN}.
PACKAGE_VERSION	Empty; each framework resolves a version as documented in its reference.
ARTIFACT_DIR	${CI_JOB_NAME_SLUG}; per-job output root.
EVIDENCE_DIR, PACKAGE_DIR, SBOM_DIR	${ARTIFACT_DIR}/evidence, ${ARTIFACT_DIR}/package, ${ARTIFACT_DIR}/sbom.
BUILD_DIR	dist globally; inherited build defaults can change it to build. Framework defaults and explicit job variables determine the effective value.

Keep the evidence and sbom directory basenames if you use the shared archive jobs; they collect directories by those names. Language-specific registry paths, credential mappings, versions, commands, and artifacts are covered in the framework reference.

Disconnected operation

Set AIRGAP_MODE: "true" for the documented disconnected behavior and "false" for connected behavior. Grype and Trivy skip database updates, ClamAV receives an offline flag, Dependency-Check disables its online update and OSS Index path, and npm audit is omitted. This switch does not mirror job images, dependencies, rule bundles, or databases. It does not disable every network call in Helm, Zarf, package publishing, or synchronization.

Your platform team must make the required images, packages, services, and usable scanner data available. An offline run with old data does not establish current vulnerability coverage. See the analysis reference.

Release and evidence jobs

See release and evidence configuration for exact activation rules, credentials, archive names, and release settings. In particular, RELEASE_PIPELINE is tested for a nonempty value by archive jobs, while release attachment requires "true". Leave it unset when you do not want release-pipeline behavior; the string "false" is still nonempty.

Kustomize image updates

See Kustomize image updates for every switch, target setting, prerequisite, and the direct-commit behavior. The default workflow updates a branch directly and does not open a merge request.

Related information

• Use the Pillars pipeline
• Pillars of Creation
• SBOM generation and evidence