Skip to main content

NCV GitLab Build Pipeline Guide

1. Objective

This guide defines the reusable GitLab CI/CD architecture for NCV Java, Flutter, container, server-deployment, desktop-release, and Apple-release workloads. The pipeline must provide:
  • fast merge-request validation;
  • unit, integration and API tests;
  • deployment to test/staging environments;
  • native Windows/Linux/macOS builds;
  • Android/iOS builds where required;
  • code signing;
  • immutable package publication;
  • release notes;
  • Experimental/Beta/Stable promotion;
  • rollback and audit evidence;
  • predictable load on the self-hosted GitLab server.

2. Non-negotiable pipeline principles

  1. Build once, promote the same artifact.
  2. Merge-request jobs never receive production or code-signing secrets.
  3. Native releases build on the matching operating system.
  4. The GitLab host is not a general high-concurrency build farm.
  5. The co-located Linux runner remains unprivileged and sequential.
  6. Release binaries live in Generic Packages, not only job artifacts.
  7. Every production deployment/release has a rollback method.
  8. Shared templates are versioned and pinned.
  9. Pipeline output must be reproducible enough to trace source commit, toolchain and build identity.
  10. Customer applications never contain GitLab administrative/personal tokens.

3. Runner architecture

3.1 Runner matrix

The first server can start with linux-small only. Windows and macOS runners are mandatory for their native platforms.

3.2 GitLab-host runner limits

The supplied config/gitlab-runner-config.toml.example enforces:
Do not mount /var/run/docker.sock. Do not allow privileged jobs. Do not run untrusted forks. If a build requires either, move it to a separate hardened runner. Verify cgroups v2 so Docker resource controls work as expected:
Expected:

4. Shared CI-template project

Create:
Repository layout:
Release template versions:
Projects pin an exact template tag:
Never include main from production projects. A breaking template change requires a major version. GitLab include: imports CI YAML only; it does not copy the template repository’s shell scripts into the consuming project’s checkout. Build the supplied ci/images/release-tools/Dockerfile, scan it, publish it to the NCV Container Registry, and have release jobs execute the helpers from /usr/local/lib/ncv-ci. After the pilot, pin the container by digest so a tag cannot silently change the release logic.

5. Standard stages

Meaning:

6. Pipeline trigger model

The shared workflow runs for:
  • merge requests;
  • semantic-version tags;
  • default branch;
  • explicitly started web pipelines;
  • schedules.
It does not create pipelines for every arbitrary branch push unless that branch has a merge request or project-specific rule. Expected flow:

7. Job dependency model

Use needs to express actual dependencies and shorten pipelines:
Avoid downloading all prior artifacts by default. Keep job outputs focused. Use resource_group for deployments that must not overlap:
This prevents concurrent deployments to the same environment.

8. Cache versus artifacts versus packages

Do not distribute production desktop applications from expiring job-artifact URLs.

9. Build identity

Every release artifact records:
Store this metadata in release notes and channel manifest.

10. Java Gradle pipeline

Project file:
Default commands:
Requirements:
  • use Gradle Wrapper;
  • pin JDK/toolchain compatibility;
  • export JUnit XML;
  • keep Gradle cache under project directory;
  • do not enable a long-running Gradle daemon in ephemeral jobs;
  • add integration-test job separately if it starts databases/services.
Example integration test:
Never use production DB credentials in CI tests.

11. Java Maven pipeline

Default commands:
Prefer Maven Wrapper and replace commands with ./mvnw after adding it. For Maven libraries, publish to GitLab’s Maven registry using project or job-token authentication. Do not publish Java libraries as arbitrary ZIPs when the native registry is appropriate.

12. Flutter validation and unit tests

Linux runner handles platform-independent checks:
Commands:
Build and host an NCV-owned Flutter CI image at an immutable internal tag. It should include the exact Flutter/Dart version and required Linux packages. Example Dockerfile concept:
The actual Dockerfile must verify downloaded source/artifact and pin the Flutter version. Do not use an unversioned public latest image.

13. Flutter Linux build

Output is typically under:
Package options:
  • .tar.gz for controlled self-update;
  • AppImage when supported by the application/update design;
  • .deb/.rpm as downloadable files.
GitLab Generic Packages can store .deb/.rpm, but GitLab does not act as a native apt/yum repository for them. Add a dedicated repository service if apt/yum consumption is required. Linux signing recommendation for self-hosted downloads:
  • calculate SHA-256;
  • create a Minisign signature using a protected signing runner/key;
  • ship the public verification key inside the application/helper;
  • verify before install.

14. Windows runner installation and policy

14.1 Host requirements

  • supported Windows version;
  • Git;
  • GitLab Runner;
  • current Flutter SDK pinned/controlled;
  • Visual Studio with Desktop development with C++ workload;
  • Windows SDK;
  • installer tooling (MSIX/Inno Setup/WiX as selected);
  • code-signing tools/certificate on a protected release runner;
  • sufficient disk for Flutter/Visual Studio/build cache.
Run:
All Windows desktop requirements must pass.

14.2 Register runner

In GitLab, create a project/group runner and obtain the runner authentication token (glrt-...). Then on Windows:
Install/start service using the approved dedicated service account:
Do not put the service-account password in a script, CI variable, Jira, or command history. Use the approved service-account provisioning process. Set tags and restrictions in GitLab:

14.3 Windows build job

Current Flutter Windows x64 output includes the architecture directory:

14.4 Windows packaging

Choose one supported package per product:
  • Inno Setup Setup.exe for direct customer distribution;
  • MSIX for Microsoft Store/managed deployment;
  • ZIP only when a dedicated updater owns installation/replacement.
Installer pipeline must:
  1. include app binary and required runtime files;
  2. set product/version/publisher/upgrade identity;
  3. preserve data/config locations;
  4. support quiet install/update where required;
  5. avoid installing writable data under executable directories;
  6. sign final executable/installer;
  7. verify signature;
  8. calculate SHA-256;
  9. test install, upgrade, restart and uninstall in a clean VM.

14.5 Authenticode signing

Keep the private signing credential on the protected Windows release runner or hardware-backed signing service. Conceptual commands:
Use the timestamp service specified by the certificate provider. Never export the private key into a normal merge-request job.

15. macOS runner installation and Apple pipeline

15.1 Host policy

  • dedicated Mac user/service account;
  • current supported macOS/Xcode for the target Flutter version;
  • Flutter pinned/controlled;
  • GitLab Runner shell executor;
  • Fastlane or approved Apple tooling;
  • signing identities/profiles in that user’s Keychain;
  • runner restricted to protected release refs;
  • FileVault and normal OS hardening enabled;
  • no general browsing/developer use on the signing runner.

15.2 Register and run

Runner config is stored under the runner user’s home directory. The shell executor runs jobs as that user, including access to its Keychain; therefore only protected trusted release code may execute there.

15.3 Flutter macOS build

Direct-download macOS apps require correct signing and notarization. App Store distribution follows the Apple/App Store Connect route.

15.4 iOS/TestFlight/App Store Connect

A protected job may call Fastlane:
Use an App Store Connect API key where suitable. Store issuer ID/key ID as protected variables and the .p8 as a protected file-type variable or approved secret store. The Fastlane lane must:
  • select the correct bundle ID/team;
  • increment/use unique build number;
  • build/sign/archive;
  • upload to TestFlight;
  • apply release notes/tester groups as approved;
  • never automatically submit production App Store review solely because a tag exists unless management explicitly adopts that policy.

16. Android build and store flow

Android can build on a separate Linux runner with sufficient resources. Do not burden linux-small with frequent heavy Android release builds if GitLab responsiveness is affected.
Signing key handling:
  • keystore as protected file variable or signing runner secret;
  • passwords as masked/protected variables;
  • release job only on protected tags;
  • never expose signing material to merge requests;
  • upload AAB to internal testing before production.

17. Container image pipeline

Do not build containers through the GitLab host’s Docker socket. Use a separate linux-container-build runner and the supplied ci/templates/container-build.yml. Example:
Requirements:
  • build with BuildKit rootless or Buildah/Podman on a compatible dedicated runner;
  • authenticate using CI_REGISTRY_USER/CI_REGISTRY_PASSWORD;
  • push commit-SHA tag;
  • release tags add semantic-version tag after validation;
  • production deploys by digest or immutable tag;
  • never rely only on latest;
  • run vulnerability/SBOM/signature steps according to product risk.

18. Test-environment deployment

The supplied SSH template expects:
Generate known-host evidence through an administrator-controlled channel. Do not turn off host-key checking. A deployment script should be idempotent and accept immutable identity:
After deployment:
Application-specific smoke tests follow the basic health check.

19. Staging and production

Production job pattern:
On Free:
  • protect release tags;
  • keep production variables protected;
  • keep Maintainer access narrow;
  • record UAT/approval in Jira;
  • review who started the manual job.
Paid protected-environment controls provide stronger technical authorization if later required.

20. Desktop release pipeline

Recommended sequence:
The package version/file name is immutable. A retry may detect that the exact same file exists; it must not overwrite an existing version with different bytes.

21. Release project variables

Each source product project defines:
Protected variables:
Prefer cross-project job-token allowlists before creating a long-lived release project token.

22. Semantic tag creation

Before tagging:
  1. main pipeline passes;
  2. version is updated in application metadata;
  3. release notes are complete;
  4. migration/compatibility risks are approved;
  5. tag creator is allowed by protected-tag policy.
Create signed/annotated tag according to project policy:
Do not move or reuse a published release tag. A correction becomes a new version.

23. Release notes automation

Pipeline may validate that RELEASE_NOTES.md contains:
  • current version;
  • management summary;
  • Jira issues;
  • verification;
  • known limitations;
  • rollback.
Example check:
Automation may assemble issue lists, but a human owns the final customer/management wording.

24. Channel promotion

Promotion job calls:
It writes:
A rollout-percentage update for the same release must preserve the rollout salt so device assignment remains stable.

25. Secret safety in pipelines

  • Keep production/signing jobs on protected refs.
  • Mark variables masked/protected/file as applicable.
  • Do not run set -x/PowerShell transcript around secrets.
  • Do not put secrets in artifacts, caches or dotenv reports.
  • Do not expose protected shell runners to arbitrary merge-request code.
  • Use dedicated service accounts.
  • Rotate leaked credentials immediately.
  • Validate that release-only public projects have no inherited exposed variables/files.

26. Pipeline performance on the supplied server

With one job at a time, three build requests per hour are reasonable when jobs average below roughly 15–20 minutes and are mostly Java/Flutter validation. Queueing is acceptable initially. Optimize before scaling:
  • cache Gradle/Maven/Pub dependencies;
  • use needs;
  • avoid duplicate builds;
  • cancel superseded pipelines through interruptible: true;
  • keep Git clone depth reasonable;
  • move Android/container/integration workloads to dedicated runners;
  • monitor queue time rather than guessing.
Scale when p95 queue time exceeds five minutes persistently or GitLab latency changes during builds.

27. Pipeline validation before adoption

For each project:
  • Merge-request validation runs.
  • Failure blocks merge.
  • JUnit/test evidence appears in GitLab.
  • Cache improves second-run duration without hiding dependencies.
  • Default branch builds/deploys test.
  • Test health/smoke check passes.
  • Tag triggers native release build.
  • Signing succeeds and verification is explicit.
  • Immutable package is visible in release project.
  • GitLab Release shows notes and asset link.
  • Experimental manifest matches SHA.
  • Beta/Stable promotion does not rebuild.
  • rollback restores prior manifest/deployment.
  • no secret appears in job log/artifact.
  • job load does not impair GitLab.

28. Troubleshooting

Job cannot find runner

Check job tags, runner pause/protection/lock settings, platform availability and token verification.

Docker job rejected because image is not allowed

Publish/review the required image into the NCV internal registry and update the runner allowlist through an infrastructure change. Do not broadly allow *.

Gradle/Maven downloads every run

Check project-local cache path, cache key, runner cache settings and whether the job runs on another runner.

Windows signing works interactively but not in CI

The runner service account may not have the certificate/private-key access or timestamp network access. Verify certificate store, account context and ACLs; do not solve by exporting the key into repository files.

macOS Keychain is locked

Use a dedicated runner account and approved Keychain-unlock process limited to protected jobs. Avoid ad-hoc plaintext passwords in YAML.

Package upload succeeds but customer gets 401

Confirm release project visibility/anonymous Package Registry pull setting, project-level endpoint, and no group-only Generic Package URL assumption.

Test deployment overlaps

Add/verify resource_group and make deployment scripts idempotent.

29. Template files included in this pack

Build and publish the supplied ci/images/release-tools/Dockerfile; GitLab YAML includes do not copy scripts into consuming repositories. The release templates run the helpers from /usr/local/lib/ncv-ci inside the versioned internal image. Pin the verified image tag and then its digest.

30. Official references