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
- Build once, promote the same artifact.
- Merge-request jobs never receive production or code-signing secrets.
- Native releases build on the matching operating system.
- The GitLab host is not a general high-concurrency build farm.
- The co-located Linux runner remains unprivileged and sequential.
- Release binaries live in Generic Packages, not only job artifacts.
- Every production deployment/release has a rollback method.
- Shared templates are versioned and pinned.
- Pipeline output must be reproducible enough to trace source commit, toolchain and build identity.
- 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 suppliedconfig/gitlab-runner-config.toml.example enforces:
/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:
4. Shared CI-template project
Create: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
6. Pipeline trigger model
The sharedworkflow runs for:
- merge requests;
- semantic-version tags;
- default branch;
- explicitly started web pipelines;
- schedules.
7. Job dependency model
Useneeds to express actual dependencies and shorten pipelines:
resource_group for deployments that must not overlap:
8. Cache versus artifacts versus packages
Do not distribute production desktop applications from expiring job-artifact URLs.
9. Build identity
Every release artifact records:10. Java Gradle pipeline
Project file:- 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.
11. Java Maven pipeline
./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:latest image.
13. Flutter Linux build
.tar.gzfor controlled self-update;- AppImage when supported by the application/update design;
.deb/.rpmas downloadable files.
.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.
14.2 Register runner
In GitLab, create a project/group runner and obtain the runner authentication token (glrt-...). Then on Windows:
14.3 Windows build job
14.4 Windows packaging
Choose one supported package per product:- Inno Setup
Setup.exefor direct customer distribution; - MSIX for Microsoft Store/managed deployment;
- ZIP only when a dedicated updater owns installation/replacement.
- include app binary and required runtime files;
- set product/version/publisher/upgrade identity;
- preserve data/config locations;
- support quiet install/update where required;
- avoid installing writable data under executable directories;
- sign final executable/installer;
- verify signature;
- calculate SHA-256;
- 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: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
15.3 Flutter macOS build
15.4 iOS/TestFlight/App Store Connect
A protected job may call Fastlane:.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 burdenlinux-small with frequent heavy Android release builds if GitLab responsiveness is affected.
- 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 separatelinux-container-build runner and the supplied ci/templates/container-build.yml.
Example:
- 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:19. Staging and production
Production job pattern:- protect release tags;
- keep production variables protected;
- keep Maintainer access narrow;
- record UAT/approval in Jira;
- review who started the manual job.
20. Desktop release pipeline
Recommended sequence:21. Release project variables
Each source product project defines:22. Semantic tag creation
Before tagging:mainpipeline passes;- version is updated in application metadata;
- release notes are complete;
- migration/compatibility risks are approved;
- tag creator is allowed by protected-tag policy.
23. Release notes automation
Pipeline may validate thatRELEASE_NOTES.md contains:
- current version;
- management summary;
- Jira issues;
- verification;
- known limitations;
- rollback.
24. Channel promotion
Promotion job calls: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.
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/verifyresource_group and make deployment scripts idempotent.
29. Template files included in this pack
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
- GitLab CI/CD: https://docs.gitlab.com/ci/
- GitLab CI YAML: https://docs.gitlab.com/ci/yaml/
- GitLab Docker executor: https://docs.gitlab.com/runner/executors/docker/
- GitLab Runner Windows: https://docs.gitlab.com/runner/install/windows/
- GitLab Runner macOS: https://docs.gitlab.com/runner/install/osx/
- GitLab BuildKit rootless: https://docs.gitlab.com/ci/docker/using_buildkit/
- GitLab Container Registry: https://docs.gitlab.com/user/packages/container_registry/
- Flutter Windows deployment: https://docs.flutter.dev/deployment/windows
- Flutter macOS deployment: https://docs.flutter.dev/deployment/macos
- Fastlane TestFlight: https://docs.fastlane.tools/actions/upload_to_testflight/