Pillars framework jobs and configuration
Select a framework using the framework selection rules.
This page describes its application-project requirements and behavior. A job's disable
switch accepts "false"; an unset switch retains the normal selection rules.
Dependency and build jobs block failures. Analysis jobs use the
context failure rules.
Package jobs are manual and nonblocking on tags unless your project overrides them.
Several framework build jobs also publish to a staging package registry. Disabling the later package job does not prevent that staging publication. Configure a writable staging destination before running those builds.
The variable defaults catalog supplies exact values for every declared framework variable, including registry paths, caches, and report settings. Variables in the tables below are the primary controls; they do not replace required application files.
npm
Provide root package.json and a matching package-lock.json. The jobs use npm;
a Yarn or pnpm lockfile alone does not select or configure this framework. Provide a
lint script and a test script, or disable the corresponding job when it is inapplicable.
The build script is optional because the build runs with --if-present.
| Job | Disable switch | Behavior and output |
|---|---|---|
npm-dependencies | NPM_DEPENDENCIES | Runs npm install --package-lock-only, fails if the lock changes, then runs npm install --include prod and npm prune. Retains node_modules. |
npm-build | NPM_BUILD | Resolves the version, runs npm run build --if-present, packs a tarball into PACKAGE_DIR, and publishes to staging. Emits build.env. |
npm-lint | NPM_LINT | Installs dependencies and runs npm run lint; requires dependency-job artifacts. |
npm-tests | NPM_TESTS | Runs npm run NPM_TEST_SCRIPT -- NPM_TEST_ARGS NPM_TEST_SHARD_ARG; retains test output and configured reports. Omitted when sharding is enabled. |
npm-audit | NPM_AUDIT | Runs npm audit, saves JSON and SARIF, and applies NPM_CONFIG_AUDIT_LEVEL, default high. Omitted with AIRGAP_MODE: "true". |
npm-package | NPM_PACKAGE | Packs and publishes on a tag when started manually. Skips a redundant publish when release and staging URLs match. Requires build and dependency artifacts. |
Version priority is PACKAGE_VERSION, commit tag, then the version in package.json
with -CI_PIPELINE_ID appended. The helper changes the checked-out package version
without creating a commit or Git tag. The build appends exclusions to .npmignore,
including source, tests, public assets, configuration files, and pipeline outputs.
Inspect the resulting tarball before distributing it.
| Setting | Default and effect |
|---|---|
NODE_VERSION | Unset; .nvmrc takes precedence when the job image exposes nvm. Otherwise the image's installed Node.js is used. |
NPM_TEST_SCRIPT, NPM_TEST_ARGS | test and empty; choose the project's actual test command and arguments. |
NPM_TEST_JUNIT_REPORT | ${EVIDENCE_DIR}/junit.xml; the test runner must produce JUnit. |
NPM_TEST_COBERTURA_REPORT | ${EVIDENCE_DIR}/coverage/cobertura-coverage.xml; the runner must produce Cobertura. |
NPM_PACKAGE_TAG | ${CI_COMMIT_REF_SLUG}; npm dist-tag used by both publication paths. |
NPM_STAGING_PUBLISH_ARGS, NPM_PUBLISH_ARGS | Empty; extra arguments for staging and release npm publish. |
DISABLE_PROJECT_NPMRC_CONFIG | false; setting "true" removes the checked-out project's .npmrc during setup. |
NPM_NPMRC_CONFIG | Unset; writes a supplied configuration to the job user's .npmrc. Project-level npm configuration can still have higher precedence unless removed. |
Registry controls use NPM_REGISTRY_* for release, NPM_STAGING_REGISTRY_* for staging,
NPM_UPSTREAM_REGISTRY_* for dependency installation, and NPM_AUDIT_REGISTRY_* for
audit. Each family supports HOST, PATH, USERNAME, PASSWORD, and TOKEN.
Release/staging hosts and tokens inherit the shared package settings; their username
and password defaults are unset. Upstream settings inherit the shared upstream values.
Audit settings are unset. The default package path is
api/v4/projects/${CI_PROJECT_ID}/packages/npm/.
Prefer the token path for the documented npm registry integration. The current
username/password setup contains inconsistent encoded-variable assignments; do not
assume Basic authentication works without an installation-specific correction.
Never commit a credential-bearing .npmrc.
npm test sharding
The ordinary test job is the default. NPM_TESTS_SHARDING: "true" selects
npm-tests-generate-pipeline, npm-tests-trigger-pipeline, and
npm-tests-pipeline-artifacts. The generated child pipeline runs parallel npm-tests
jobs and npm-tests-recombine. The default shard count is NPM_TESTS_SHARD_COUNT: 5.
The generated arguments use Vitest's blob reporter and shard flags; other test runners
need compatible project customization.
This feature downloads template files using PIPELINE_PROJECT_ID and PIPELINE_REF,
then downloads child-job artifacts using the job token. The platform team must configure
an accessible template copy, its actual project ID and revision, and API permissions.
Changing the main include alone does not update those download settings.
Keep sharding disabled until that installed workflow is validated. The documented
implementation declares NPM_TEST_MERGE_COMMAND but executes
NPM_TESTS_MERGE_COMMAND; its generated configuration also retains shared references
that need to be available in the child pipeline. NPM_TESTS_RECOMBINE: "false" removes
the recombination job, but the artifact collector still expects its output.
NPM_TESTS_COVERAGE_MERGE_COMMAND defaults to
npx vitest-coverage-merge -o ${EVIDENCE_DIR}/coverage --normalize.
These constraints are why enabling sharding is more than setting a shard count.
Gradle
Provide a root Gradle build with the tasks used below. The jobs invoke gradle from
the configured image, not ./gradlew. A wrapper in your project does not by itself
select the runtime version. Use GRADLE_IMAGE for the approved toolchain image.
| Job | Disable switch | Behavior and output |
|---|---|---|
gradle-build | GRADLE_BUILD | Runs gradle build and gradle publish with generated repository init scripts and the resolved version. Copies build/**/*.jar to PACKAGE_DIR; publishes to staging. |
gradle-tests | GRADLE_TESTS | Runs gradle --build-cache clean check jacocoTestReport, retains evidence, and declares JUnit output in ${EVIDENCE_DIR}/*.xml. Requires those tasks and JaCoCo configuration. |
gradle-package | GRADLE_PACKAGE | Runs release publication manually on tags; skips publication when release and staging URLs match. |
Version priority is PACKAGE_VERSION, commit tag, then the version reported by
gradle properties with -CI_PIPELINE_ID appended. GRADLE_USER_HOME defaults to
.gradle. The pipeline sets JUNIT_JUPITER_OUTPUT_DIR for the test job, but your Gradle
report tasks still need to write reports to the expected locations.
Repository families are GRADLE_REPOSITORY_*, GRADLE_STAGING_REPOSITORY_*, and
GRADLE_UPSTREAM_REPOSITORY_*. Each has HOST, PATH, USERNAME, PASSWORD,
TOKEN, TOKEN_NAME, and AUTH_TYPE. Hosts and username/password fields inherit the
corresponding shared package settings. Paths default to
api/v4/projects/${CI_PROJECT_ID}/packages/maven. Tokens default directly to
${CI_JOB_TOKEN}, the header name to Job-Token, and authentication to
header(HttpHeaderAuthentication). Configure the framework-specific token when changing
that default. Declared GRADLE_PACKAGE_VERSION and GRADLE_STAGING_PACKAGE_VERSION
alias the shared value; the job's version-resolution helper uses PACKAGE_VERSION.
pip
Provide requirements.txt. Add dev-requirements.txt with test dependencies, including
coverage, when required. Packaging requires pyproject.toml with exactly one literal
version entry under [project]; dynamic versioning and a setup-only project do not
satisfy the current version helper.
| Job | Disable switch | Behavior and output |
|---|---|---|
pip-dependencies | PIP_DEPENDENCIES | Creates .venv, installs requirements.txt, and retains the environment as an artifact. |
pip-build | PIP_BUILD | Installs PIP_BUILD_PACKAGES, updates the project version, runs python -m build, and uploads distributions to staging with Twine. Retains build output and emits build.env. |
pip-tests | PIP_TESTS | Activates .venv, installs optional dev-requirements.txt, then runs coverage run -m unittest discover. Writes HTML, XML, JSON, and LCOV reports. |
pip-package | PIP_PACKAGE | Manually uploads build distributions to the release registry on tags when its URL differs from staging. |
PIP_BUILD_PACKAGES defaults to build==1.3.0 twine==6.2.0. The toolchain is selected
by PIP_IMAGE; changing PYTHON_VERSION alone does not change this fixed pip image.
Tests add the project's src directory to PYTHONPATH when it exists.
Version priority is PACKAGE_VERSION without a leading v, commit tag without a
leading v, then the base project version followed by .devCI_PIPELINE_ID.
PIP_DEFAULT_PATH defaults to /api/v4/projects/${CI_PROJECT_ID}/packages/pypi for
staging and release publication. Upload credentials prefer the relevant shared username
and password, falling back to gitlab-ci-token and the shared token.
Set PIP_EXTRA_INDEX_URL for a complete dependency-index override. When unset and
UPSTREAM_PACKAGE_HOST is present, the pipeline builds it using the shared upstream
credentials and PIP_UPSTREAM_REGISTRY_PATH, whose default is
/api/v4/groups/${CI_PROJECT_NAMESPACE_ID}/-/packages/pypi/simple/.
Treat an index URL containing credentials as a secret.
Poetry
Provide matching pyproject.toml and poetry.lock. The dependency job checks their
consistency. Configure the coverage runner in the project because tests use
poetry run coverage run without a command-line test target.
| Job | Disable switch | Behavior and output |
|---|---|---|
poetry-dependencies | POETRY_DEPENDENCIES | Runs poetry check --lock and poetry install; retains .venv. When GITLAB_CI_USER is set, configures the smoothglue-packages source with that user and CI_JOB_TOKEN. |
poetry-build | POETRY_BUILD | Sets the version, builds into BUILD_DIR, publishes to the staging repository, and copies distributions into PACKAGE_DIR. |
poetry-tests | POETRY_TESTS | Installs all dependency groups, runs coverage, and writes HTML, XML, JSON, and LCOV reports. |
poetry-package | POETRY_PACKAGE | Manually publishes distributions on tags when release and staging URLs differ. |
PYTHON_VERSION: "3.12" and POETRY_VERSION: "2.1.0" form the default Poetry image
reference. Select only combinations available in your installation's image registry.
Version priority is PACKAGE_VERSION, commit tag, then the current Poetry version with
-CI_PIPELINE_ID appended and normalized by Poetry.
Registry families are POETRY_PUBLISH_REGISTRY_*, POETRY_STAGING_REGISTRY_*, and
POETRY_UPSTREAM_REGISTRY_*, each with HOST, PATH, USERNAME, and PASSWORD.
Publish/staging hosts inherit the shared package hosts; their paths use
POETRY_DEFAULT_PATH, default /api/v4/projects/${CI_PROJECT_ID}/packages/pypi.
The upstream defaults to ${CI_SERVER_HOST} and the group PyPI simple-index path.
Credential defaults use gitlab-ci-token and ${CI_JOB_TOKEN}.
Poetry's named sources use POETRY_HTTP_BASIC_UPSTREAM_*,
POETRY_HTTP_BASIC_STAGING_*, and POETRY_HTTP_BASIC_PUBLISH_* username/password
variables. The current publish aliases refer to POETRY_REGISTRY_USERNAME and
POETRY_REGISTRY_PASSWORD, which have no declared defaults. For publication, set
POETRY_HTTP_BASIC_PUBLISH_USERNAME and POETRY_HTTP_BASIC_PUBLISH_PASSWORD
explicitly to the approved account and token. Do not assume the publish-registry
username/password fields automatically repair those aliases.
Go
Provide go.mod and a GoReleaser configuration suitable for the build and release jobs.
Set GO_MODULE_DIR, default ., to the module directory for a nested project. The jobs
change to that directory and resolve evidence paths relative to the GitLab project.
Detection of several modules does not build each one separately.
| Job | Disable switch | Behavior and output |
|---|---|---|
go-dependencies | GO_DEPENDENCIES | Runs go mod tidy, download, graph, and verify; retains .go-cache and evidence. |
goreleaser-build | GO_BUILD | Runs goreleaser build --snapshot --clean --single-target. Retains module target/dist and dist for one day. |
go-lint | GO_LINT_TESTS | Runs golangci-lint and retains JSON, HTML, Checkstyle, Code Climate, JUnit, SARIF, and text outputs. |
go-tests | GO_TESTS | Runs go test with package-wide coverage; retains coverage.out, HTML coverage, and test logs. |
go-audit | GO_AUDIT_PACKAGE | Runs gosec with -no-fail, excluding generated code, vendor, testdata, and the module cache. Findings are reports, not a vulnerability gate. |
goreleaser-package | GO_PACKAGE | Runs goreleaser release --clean manually on tags using the project's GoReleaser configuration and GITLAB_TOKEN, default ${CI_JOB_TOKEN}. |
GOFLAGS defaults to -buildvcs=false; module, binary, and build caches are under
.go-cache. GOLANG_IMAGE selects the toolchain. The separately declared
GOLANG_VERSION does not interpolate into the default image reference.
For example, merge these non-secret settings into your existing pipeline variables:
variables:
GO_MODULE_DIR: "services/api"
CMake
The source directory is CMAKE_SOURCE_DIR if set, otherwise the repository root when
it contains CMakeLists.txt, otherwise the first sorted nested match. Set the directory
explicitly for a repository with multiple native projects. The configured image must
contain CMake, CTest, clang-tidy, cppcheck, and gcovr; the initial tool check requires
all five even if a later analysis job is disabled.
| Job | Disable switch | Behavior and output |
|---|---|---|
cmake-dependencies | CMAKE_DEPENDENCIES | Checks tools and source discovery. It does not install all project dependencies automatically. |
cmake-build | CMAKE_BUILD | Configures and builds with CMake. Uses CPack when available, otherwise archives the build directory; uploads files to staging Generic Packages. |
cmake-lint | CMAKE_LINT | Creates a compilation database and runs clang-tidy and cppcheck. |
cmake-tests | CMAKE_TESTS | Builds with coverage flags, runs CTest, and generates JUnit, Cobertura, and HTML coverage. |
cmake-package | CMAKE_PACKAGE | Manually uploads packages on tags when the release URL differs from staging. |
Primary controls are CMAKE_BUILD_TYPE (Release), CMAKE_COVERAGE_BUILD_TYPE
(Debug), CMAKE_GENERATOR (Ninja), CMAKE_ARGS (configure arguments),
CMAKE_BUILD_ARGS (native build arguments), CMAKE_TEST_ARGS (CTest arguments), and
CMAKE_COVERAGE_FLAGS (--coverage). Build and coverage directories default to
${BUILD_DIR}/cpp and ${BUILD_DIR}/coverage. Report-path settings are listed in the
defaults catalog.
Version priority is PACKAGE_VERSION, commit tag, then a version parsed from the
project(... VERSION ...) declaration with -CI_PIPELINE_ID appended. The parser is
line-oriented; use PACKAGE_VERSION when your declaration is not recognized. The
fallback base version is 0.0.0.
CMAKE_PACKAGE_* and CMAKE_STAGING_PACKAGE_* have HOST, PATH, USERNAME,
PASSWORD, and TOKEN fields. They inherit the shared release/staging settings;
paths default to api/v4/projects/${CI_PROJECT_ID}/packages/generic.
CMAKE_PACKAGE_NAME defaults to ${CI_PROJECT_NAME}. Upload URLs append the package
name, resolved version, and filename. Username or password being present selects Basic
authentication; otherwise the script sends the token in a JOB-TOKEN header.
.NET
The target is DOTNET_PROJECT if set, otherwise the first sorted root solution,
a root .csproj, or the first sorted nested .csproj. A nested solution is detected
for inclusion but is not automatically selected as the build target. Set it explicitly.
When building a solution, also set DOTNET_PUBLISH_PROJECT to the application project.
| Job | Disable switch | Behavior and output |
|---|---|---|
dotnet-dependencies | DOTNET_DEPENDENCIES | Generates NuGet.ci.config, restores packages, and retains the NuGet cache and obj directories. |
dotnet-build | DOTNET_BUILD | Builds, optionally packs and publishes NuGet packages to staging, then publishes application output into ${BUILD_DIR}/dotnet. |
dotnet-tests | DOTNET_TESTS | Runs tests with TRX and XPlat coverage, converts available TRX to JUnit, and aggregates coverage. |
dotnet-package | DOTNET_PACKAGE | Manually publishes .nupkg build artifacts on tags when the release URL differs from staging. |
DOTNET_CONFIGURATION defaults to Release. DOTNET_PACKAGE: "false" also disables
packing and staging NuGet publication inside the build job. Use it for an application
that only distributes a container image. Otherwise a build that produces no .nupkg
fails. Configure your test projects with the test SDK and coverage collector required
by dotnet test --collect:"XPlat Code Coverage".
Version priority is PACKAGE_VERSION, commit tag, then the MSBuild version from the
first sorted project with -ci.CI_PIPELINE_ID appended, using 0.0.0 if unavailable.
Restore uses the shared upstream host and credentials, with GitLab fallbacks, and
DOTNET_UPSTREAM_REGISTRY_PATH, defaulting to the group's NuGet endpoint. The generated
restore configuration also includes nuget.org; AIRGAP_MODE does not remove it.
Staging and release push use DOTNET_STAGING_REGISTRY_PATH and
DOTNET_PUBLISH_REGISTRY_PATH, both defaulting to the project's NuGet endpoint, and
the matching shared host/token. A repository's custom restore configuration is not
automatically substituted for NuGet.ci.config.
Example for a solution that distributes only a container:
variables:
DOTNET_PROJECT: "Example.sln"
DOTNET_PUBLISH_PROJECT: "src/Api/Api.csproj"
DOTNET_PACKAGE: "false"