> ## Documentation Index
> Fetch the complete documentation index at: https://deployment.naudecoreventures.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NCV GitLab Build Pipeline Guide

> Reusable Java, Flutter, Windows, Linux, deployment and release pipeline patterns

# 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

| Runner tag | Host | Executor | Allowed workloads | Secrets |
| - | - | - | - | - |
| `linux-small` | Initial GitLab server | Docker | lint, unit tests, small Java/Flutter validation, packaging scripts | no production/signing secrets |
| `linux-container-build` | Separate Linux runner | Docker/Podman/Buildah | OCI image build/push | registry job credentials only |
| `linux-integration` | Separate Linux runner when needed | Docker/Kubernetes/shell | DB/cache/broker integration tests | test-only secrets |
| `windows-x64` | Separate Windows machine/VM | Shell/PowerShell | protected Flutter Windows release build/package | Windows signing credential only on protected runner |
| `windows-x64-test` | Optional separate Windows machine/VM | Shell/PowerShell | Windows integration/UI tests | no signing credential |
| `macos-arm64` | Separate Mac | Shell | protected Flutter macOS/iOS build and signing | Apple signing/App Store credentials |

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:

```toml theme={null}
concurrent = 1
limit = 1
cpus = "2"
memory = "8g"
privileged = false
```

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:

```bash theme={null}
stat -fc %T /sys/fs/cgroup
```

Expected:

```text theme={null}
cgroup2fs
```

## 4. Shared CI-template project

Create:

```text theme={null}
ncv/platform/ci-templates
```

Repository layout:

```text theme={null}
ci/templates/
├── common.yml
├── java-gradle.yml
├── java-maven.yml
├── flutter.yml
├── container-build.yml
├── deploy.yml
└── release.yml
scripts/
├── publish-generic-package.sh
├── create-gitlab-release.sh
└── promote-channel.sh
ci/images/release-tools/
├── Dockerfile
└── README.md
```

Release template versions:

```text theme={null}
v1.0.0
v1.1.0
v2.0.0
```

Projects pin an exact template tag:

```yaml theme={null}
include:
  - project: ncv/platform/ci-templates
    ref: v1.0.0
    file:
      - /ci/templates/common.yml
      - /ci/templates/java-gradle.yml
```

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

```yaml theme={null}
stages:
  - validate
  - test
  - build
  - package
  - deploy_test
  - verify_test
  - release
  - promote
```

Meaning:

| Stage | Purpose |
| - | - |
| `validate` | formatting, lint, static analysis, configuration validation |
| `test` | unit/component/integration tests |
| `build` | compilation and native build output |
| `package` | installer/archive/image preparation and signing |
| `deploy_test` | deploy default-branch build to test |
| `verify_test` | smoke/API/acceptance checks against test |
| `release` | immutable package upload and GitLab Release creation |
| `promote` | channel pointer or production deployment change |

## 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:

```text theme={null}
feature branch + MR
  └─ validate + test

main
  └─ validate + test + build + deploy test + verify

vX.Y.Z tag
  └─ validate + test + native build + sign + package + release

manual promotion
  └─ Experimental -> Beta -> Stable manifest update
```

## 7. Job dependency model

Use `needs` to express actual dependencies and shorten pipelines:

```yaml theme={null}
package:windows:
  needs:
    - job: windows:build
      artifacts: true
```

Avoid downloading all prior artifacts by default. Keep job outputs focused.

Use `resource_group` for deployments that must not overlap:

```yaml theme={null}
deploy:test:
  resource_group: "$CI_PROJECT_PATH_SLUG-test"
```

This prevents concurrent deployments to the same environment.

## 8. Cache versus artifacts versus packages

| Mechanism | Purpose | Retention |
| - | - | - |
| Cache | Reusable dependencies/tool downloads; not authoritative | Disposable |
| Job artifact | Pipeline handoff, reports, temporary build output | Usually 7–14 days |
| Generic Package | Immutable release binary | Product support/retention period |
| Container Registry | Immutable deployable OCI images | Cleanup policy with rollback retention |
| GitLab Release | Human-readable release metadata and asset links | Long-lived |

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

## 9. Build identity

Every release artifact records:

```text theme={null}
product version:  7.2.0
Git tag:          v7.2.0
Git commit:       full SHA
pipeline:         CI_PIPELINE_ID / CI_PIPELINE_URL
build identity:   7.2.0+pipeline.<pipeline iid>
platform:         windows/linux/macos
architecture:     x64/arm64
SHA-256:          lowercase 64-character digest
signature:        Authenticode/minisign/Apple/notarization as applicable
```

Store this metadata in release notes and channel manifest.

## 10. Java Gradle pipeline

Project file:

```yaml theme={null}
include:
  - project: ncv/platform/ci-templates
    ref: v1.0.0
    file:
      - /ci/templates/common.yml
      - /ci/templates/java-gradle.yml
      - /ci/templates/deploy.yml

java:test:
  extends: .java_gradle_test

java:build:
  extends: .java_gradle_build
  needs:
    - java:test
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
    - if: '$CI_COMMIT_TAG'
```

Default commands:

```bash theme={null}
./gradlew --no-daemon --stacktrace test
./gradlew --no-daemon --stacktrace assemble
```

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:

```yaml theme={null}
java:integration-test:
  image: gradle:8-jdk21
  stage: test
  services:
    - name: postgres:17
      alias: postgres
    - name: redis:8-alpine
      alias: redis
  variables:
    POSTGRES_DB: app_test
    POSTGRES_USER: app_test
    POSTGRES_PASSWORD: test-only-not-production
    DATABASE_URL: jdbc:postgresql://postgres:5432/app_test
    REDIS_URL: redis://redis:6379
  script:
    - ./gradlew --no-daemon integrationTest
  artifacts:
    when: always
    reports:
      junit:
        - '**/build/test-results/integrationTest/*.xml'
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
```

Never use production DB credentials in CI tests.

## 11. Java Maven pipeline

```yaml theme={null}
include:
  - project: ncv/platform/ci-templates
    ref: v1.0.0
    file:
      - /ci/templates/common.yml
      - /ci/templates/java-maven.yml

maven:test:
  extends: .java_maven_test

maven:build:
  extends: .java_maven_build
  needs:
    - maven:test
```

Default commands:

```bash theme={null}
mvn --batch-mode --errors --fail-at-end test
mvn --batch-mode --errors -DskipTests package
```

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:

```yaml theme={null}
flutter:analyze:
  extends: .flutter_analyze

flutter:test:
  extends: .flutter_test
```

Commands:

```bash theme={null}
flutter pub get
dart format --output=none --set-exit-if-changed .
flutter analyze --fatal-infos --fatal-warnings
flutter test
```

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:

```dockerfile theme={null}
FROM ubuntu:24.04
ARG FLUTTER_VERSION
# Install only reviewed dependencies, fetch exact Flutter tag, run flutter doctor.
```

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

```yaml theme={null}
linux:build:
  extends: .flutter_build_linux
  needs:
    - flutter:analyze
    - flutter:test
  rules:
    - if: '$CI_COMMIT_TAG'
```

Output is typically under:

```text theme={null}
build/linux/<architecture>/release/bundle/
```

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:

```powershell theme={null}
flutter doctor -v
```

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:

```powershell theme={null}
cd C:\GitLab-Runner
.\gitlab-runner.exe register `
  --non-interactive `
  --url "https://code.naudecoreventures.com" `
  --token $env:GITLAB_RUNNER_TOKEN `
  --executor "shell" `
  --shell "powershell" `
  --description "ncv-windows-x64-release"
```

Install/start service using the approved dedicated service account:

```powershell theme={null}
.\gitlab-runner.exe install --user ".\ncv-gitlab-runner" --password '<entered-securely>'
.\gitlab-runner.exe start
.\gitlab-runner.exe verify
```

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:

```text theme={null}
windows-x64
run untagged: false
protected: true for the signing runner
locked to project/group as appropriate
```

## 14.3 Windows build job

```yaml theme={null}
windows:build:
  stage: build
  tags:
    - windows-x64
  before_script:
    - flutter --version
    - flutter doctor -v
    - flutter pub get
  script:
    - flutter build windows --release --build-name $env:PACKAGE_VERSION --build-number $env:CI_PIPELINE_IID
  artifacts:
    paths:
      - build/windows/x64/runner/Release/
    expire_in: 14 days
  rules:
    - if: '$CI_COMMIT_TAG'
```

Current Flutter Windows x64 output includes the architecture directory:

```text theme={null}
build/windows/x64/runner/Release/
```

## 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:

```powershell theme={null}
signtool sign `
  /fd SHA256 `
  /tr https://<approved-timestamp-server> `
  /td SHA256 `
  /n "<NCV certificate subject>" `
  .release\Product-Setup.exe

signtool verify /pa /v .release\Product-Setup.exe
```

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

```bash theme={null}
gitlab-runner register \
  --non-interactive \
  --url 'https://code.naudecoreventures.com' \
  --token "$GITLAB_RUNNER_TOKEN" \
  --executor shell \
  --description 'ncv-macos-arm64-release'

gitlab-runner install
gitlab-runner start
gitlab-runner verify
```

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

```yaml theme={null}
macos:build:
  stage: build
  tags:
    - macos-arm64
  script:
    - flutter --version
    - flutter doctor -v
    - flutter pub get
    - flutter build macos --release --build-name "$PACKAGE_VERSION" --build-number "$CI_PIPELINE_IID"
  artifacts:
    paths:
      - build/macos/Build/Products/Release/*.app
    expire_in: 14 days
  rules:
    - if: '$CI_COMMIT_TAG'
```

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:

```yaml theme={null}
ios:testflight:
  stage: release
  tags:
    - macos-arm64
  script:
    - bundle install
    - bundle exec fastlane ios beta
  rules:
    - if: '$CI_COMMIT_TAG'
      when: manual
  manual_confirmation: "Upload this signed build to TestFlight?"
```

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.

```yaml theme={null}
android:build:
  extends: .flutter_build_android
  needs:
    - flutter:analyze
    - flutter:test
  rules:
    - if: '$CI_COMMIT_TAG'
```

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:

```yaml theme={null}
include:
  - project: ncv/platform/ci-templates
    ref: v1.0.0
    file:
      - /ci/templates/common.yml
      - /ci/templates/container-build.yml

container:build:
  extends: .container_build
  variables:
    CONTAINERFILE: Dockerfile
    IMAGE_TAG: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
```

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:

```text theme={null}
TEST_DEPLOY_SSH_KEY          protected file variable
TEST_DEPLOY_KNOWN_HOSTS      non-secret but integrity-sensitive file/value
TEST_DEPLOY_USER
TEST_DEPLOY_HOST
TEST_DEPLOY_PATH
TEST_ENVIRONMENT_URL
```

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:

```bash theme={null}
./deploy.sh <commit-or-image-digest>
```

After deployment:

```bash theme={null}
curl --fail-with-body --retry 12 --retry-delay 5 \
  "$TEST_ENVIRONMENT_URL/health"
```

Application-specific smoke tests follow the basic health check.

## 19. Staging and production

Production job pattern:

```yaml theme={null}
deploy:production:
  stage: promote
  resource_group: "$CI_PROJECT_PATH_SLUG-production"
  environment:
    name: production
    url: "$PRODUCTION_URL"
  script:
    - ./deploy-production.sh "$RELEASE_ID"
    - ./verify-production.sh "$RELEASE_ID"
  when: manual
  allow_failure: false
  manual_confirmation: "Deploy this exact release to production?"
  rules:
    - if: '$CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+$/'
```

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:

```text theme={null}
semantic version tag
  -> validate/test
  -> native platform build
  -> package
  -> sign and verify
  -> SHA-256
  -> upload immutable Generic Package to ncv-releases/<product>
  -> create GitLab Release in ncv-releases/<product>
  -> attach package link
  -> promote Experimental automatically or manually by policy
  -> QA/pilot
  -> promote Beta manually
  -> promote Stable manually
```

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:

```text theme={null}
PRODUCT_ID
RELEASE_PROJECT_ID
RELEASE_PROJECT_PATH
PACKAGE_NAME
RELEASE_PLATFORM
RELEASE_ARCHITECTURE
RELEASE_NOTES_FILE
SIGNATURE_TYPE
```

Protected variables:

```text theme={null}
RELEASE_PROJECT_TOKEN       only if CI_JOB_TOKEN cannot satisfy cross-project action
WINDOWS_SIGNING_*           protected Windows runner only
APPLE_*                     protected macOS runner only
PRODUCTION_*                protected production job only
```

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:

```bash theme={null}
git switch main
git pull --ff-only origin main
git tag -a v7.2.0 -m 'Lyt-Soft 7.2.0'
git push origin v7.2.0
```

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:

```bash theme={null}
test -s RELEASE_NOTES.md
grep -F "$CI_COMMIT_TAG" RELEASE_NOTES.md
grep -F '## Rollback' RELEASE_NOTES.md
grep -F '## Verification evidence' RELEASE_NOTES.md
```

Automation may assemble issue lists, but a human owns the final customer/management wording.

## 24. Channel promotion

Promotion job calls:

```bash theme={null}
./scripts/promote-channel.sh \
  "$PRODUCT_ID" "$RELEASE_CHANNEL" "$PACKAGE_VERSION" "$BUILD_ID" \
  "$RELEASE_PLATFORM" "$RELEASE_ARCHITECTURE" \
  "$ARTIFACT_URL" "$ARTIFACT_FILE_NAME" "$ARTIFACT_SIZE" "$ARTIFACT_SHA256" \
  "$RELEASE_NOTES_URL" "$MANDATORY_UPDATE" "$ROLLOUT_PERCENTAGE" \
  "$MINIMUM_SUPPORTED_VERSION" "$SIGNATURE_TYPE" "$SIGNATURE_URL"
```

It writes:

```text theme={null}
channels/<product>/<platform>/<architecture>/<channel>.json
```

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

```text theme={null}
ci/templates/common.yml
ci/templates/java-gradle.yml
ci/templates/java-maven.yml
ci/templates/flutter.yml
ci/templates/container-build.yml
ci/templates/deploy.yml
ci/templates/release.yml

ci/examples/.gitlab-ci.java-gradle.yml
ci/examples/.gitlab-ci.maven.yml
ci/examples/.gitlab-ci.flutter-desktop.yml
```

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

* GitLab CI/CD: [https://docs.gitlab.com/ci/](https://docs.gitlab.com/ci/)
* GitLab CI YAML: [https://docs.gitlab.com/ci/yaml/](https://docs.gitlab.com/ci/yaml/)
* GitLab Docker executor: [https://docs.gitlab.com/runner/executors/docker/](https://docs.gitlab.com/runner/executors/docker/)
* GitLab Runner Windows: [https://docs.gitlab.com/runner/install/windows/](https://docs.gitlab.com/runner/install/windows/)
* GitLab Runner macOS: [https://docs.gitlab.com/runner/install/osx/](https://docs.gitlab.com/runner/install/osx/)
* GitLab BuildKit rootless: [https://docs.gitlab.com/ci/docker/using\_buildkit/](https://docs.gitlab.com/ci/docker/using_buildkit/)
* GitLab Container Registry: [https://docs.gitlab.com/user/packages/container\_registry/](https://docs.gitlab.com/user/packages/container_registry/)
* Flutter Windows deployment: [https://docs.flutter.dev/deployment/windows](https://docs.flutter.dev/deployment/windows)
* Flutter macOS deployment: [https://docs.flutter.dev/deployment/macos](https://docs.flutter.dev/deployment/macos)
* Fastlane TestFlight: [https://docs.fastlane.tools/actions/upload\_to\_testflight/](https://docs.fastlane.tools/actions/upload_to_testflight/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.