> ## 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 Developer Guide for GitLab and Jira

> Developer onboarding, Jira-linked Git workflow, merge requests, tests, releases and secrets

# NCV Developer Guide for GitLab and Jira

## 1. Purpose

This guide defines how NCV developers use Jira and GitLab after the Azure DevOps migration.

The systems have different responsibilities:

```text theme={null}
Jira Cloud
  └─ business objective, epic, story, bug, acceptance, priority and ownership

GitLab Self-Managed
  └─ source, branch, commit, merge request, tests, build, deployment, package and release
```

Every meaningful code change must be traceable from a Jira issue to a GitLab branch, commits, merge request, pipeline, deployment, and—when customer-facing—a release note.

## 2. First-day setup

## 2.1 Account and security

1. Accept the GitLab invitation for `https://code.naudecoreventures.com`.
2. Set a unique password stored in the approved password manager.
3. Enable two-factor authentication immediately.
4. Save recovery codes in the password manager, not on the workstation desktop.
5. Confirm the correct NCV group/project role.
6. Do not create a personal access token unless a specific workflow requires it.

## 2.2 Install Git and Git LFS

Ubuntu/Debian:

```bash theme={null}
sudo apt update
sudo apt install -y git git-lfs
```

Windows:

* Install the current Git for Windows release.
* Install Git LFS if it is not included/activated.
* Use PowerShell, Windows Terminal, IntelliJ, Android Studio, or Visual Studio as appropriate.

Initialize LFS once per workstation account:

```bash theme={null}
git lfs install
```

Verify:

```bash theme={null}
git --version
git lfs version
```

## 2.3 Configure Git identity

Use the name and email associated with the GitLab account:

```bash theme={null}
git config --global user.name "Your Name"
git config --global user.email "your.name@naudecoreventures.com"
git config --global init.defaultBranch main
git config --global fetch.prune true
git config --global pull.ff only
```

Review:

```bash theme={null}
git config --global --list
```

`pull.ff only` prevents accidental local merge commits. Explicitly rebase or merge when the branch workflow requires it.

## 2.4 Create an SSH key

Use Ed25519:

```bash theme={null}
ssh-keygen -t ed25519 -a 100 \
  -C "your.name@naudecoreventures.com" \
  -f ~/.ssh/id_ed25519_ncv_gitlab
```

Load it:

```bash theme={null}
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_ncv_gitlab
```

Copy the public key:

```bash theme={null}
cat ~/.ssh/id_ed25519_ncv_gitlab.pub
```

Add it in GitLab under **Edit profile > Access > SSH keys**. Never upload the private key.

Optional SSH config:

```sshconfig theme={null}
Host ncv-gitlab
  HostName code.naudecoreventures.com
  User git
  IdentityFile ~/.ssh/id_ed25519_ncv_gitlab
  IdentitiesOnly yes
```

Test:

```bash theme={null}
ssh -T ncv-gitlab
```

Clone:

```bash theme={null}
git clone ncv-gitlab:ncv/products/<project>.git
```

## 3. Repository layout and ownership

Expected group layout:

```text theme={null}
ncv/
├── platform/
│   ├── ci-templates
│   ├── ci-images
│   ├── release-schemas
│   └── release-dashboard          optional later
├── infrastructure/
│   ├── gitlab-platform
│   └── environment-deployments
├── products/
│   ├── lyt-soft
│   ├── kazang-pos
│   ├── smart-invoice-api
│   └── ...
└── libraries/
    └── shared libraries

ncv-releases/
├── lyt-soft
├── kazang-pos
└── ...
```

Product source projects are private. Release-only projects must not contain proprietary source, credentials, internal logs, customer records, or debug dumps.

Every project must have:

* a named Product Owner;
* a named technical Maintainer;
* a README containing build/run/test instructions;
* a CODEOWNERS file where appropriate;
* a `.gitlab-ci.yml`;
* a rollback method;
* a service/dependency owner;
* a link to the Jira product/project.

## 4. Jira-linked branch workflow

## 4.1 Work starts in Jira

Before creating a branch, the Jira item must include:

* problem/business objective;
* required outcome;
* acceptance criteria;
* owner;
* priority;
* known risk/dependencies.

Do not create vague branches for work that is not represented in Jira, except an approved emergency incident branch. The incident must be backfilled immediately.

## 4.2 Branch naming

Use:

```text theme={null}
<JIRA-KEY>-<short-kebab-description>
```

Examples:

```text theme={null}
SYN-264-fix-invoice-retry
HYP-12-harden-base-server
POS-418-add-offline-stock-queue
```

Prefixes such as `feature/` are optional only if the repository team consistently uses them:

```text theme={null}
feature/SYN-264-fix-invoice-retry
fix/POS-418-receipt-timeout
```

The Jira key is mandatory.

Create from current `main`:

```bash theme={null}
git switch main
git pull --ff-only origin main
git switch -c SYN-264-fix-invoice-retry
```

## 4.3 Commit messages

Use this pattern:

```text theme={null}
<JIRA-KEY> <type>: <imperative summary>
```

Recommended types:

```text theme={null}
feat, fix, refactor, test, docs, build, ci, chore, perf, security
```

Examples:

```text theme={null}
SYN-264 fix: retry transient Smart Invoice failures
SYN-264 test: cover duplicate submission response
POS-418 perf: batch offline stock writes
```

A good commit:

* has one coherent purpose;
* keeps the repository buildable where practicable;
* includes tests with the behaviour change;
* does not contain generated output, secrets, or local IDE state;
* explains why when the reason is not obvious.

Do not use:

```text theme={null}
fix stuff
updates
wip
final final
```

## 5. Daily development flow

```bash theme={null}
# Begin from current main
git switch main
git pull --ff-only origin main
git switch -c SYN-264-fix-invoice-retry

# Work and test
git status
git diff
git add <specific-files>
git commit -m "SYN-264 fix: retry transient Smart Invoice failures"

# Rebase on latest main before the MR is merged
git fetch origin
git rebase origin/main

# Push
git push -u origin SYN-264-fix-invoice-retry
```

Do not use `git add .` without reviewing `git status` and `git diff --staged`.

After rebasing an already-pushed personal branch:

```bash theme={null}
git push --force-with-lease
```

Never use plain `--force` against shared/protected branches.

## 6. Merge requests

## 6.1 When to open

Open a Draft merge request early when feedback is useful. Mark it ready only when:

* acceptance criteria are met;
* local tests pass;
* pipeline passes;
* the description is complete;
* secrets/debug output are removed;
* release/rollback impact is stated;
* migrations are reviewed;
* release-note text is included when customer-facing.

## 6.2 Required title

```text theme={null}
<JIRA-KEY>: <business-readable change>
```

Example:

```text theme={null}
SYN-264: Retry temporary Smart Invoice submission failures
```

## 6.3 Required description

Use `templates/merge_request_template.md`. At minimum include:

* Jira issue and outcome;
* implementation summary;
* risk;
* exact tests/evidence;
* migration/config impact;
* release-note wording;
* rollback method.

## 6.4 Review standard

Reviewers assess:

1. correctness and business outcome;
2. data integrity and backward compatibility;
3. security and secret handling;
4. test quality;
5. observability and failure behaviour;
6. maintainability;
7. deployment and rollback;
8. release-note completeness.

A reviewer must not approve merely because the pipeline is green. CI catches known checks; it does not replace engineering judgment.

## 6.5 Merge policy

* `main` is protected.
* Direct pushes to `main` are disabled.
* A successful pipeline is required.
* Required review is governed by repository policy and available GitLab tier controls.
* Delete feature branches after merge.
* Prefer squash when the branch contains noisy fix-up commits; retain meaningful multi-commit history where valuable.
* Use merge commit, squash, or fast-forward consistently per project; document the choice in the project README.

## 7. Local verification commands

Each project README remains authoritative. These are NCV defaults.

## 7.1 Flutter

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

Coverage when required:

```bash theme={null}
flutter test --coverage
```

Desktop builds:

```bash theme={null}
# On Linux
flutter config --enable-linux-desktop
flutter build linux --release

# On Windows
flutter config --enable-windows-desktop
flutter build windows --release

# On macOS
flutter config --enable-macos-desktop
flutter build macos --release
```

Native Windows and Apple builds run on their matching operating systems; the Linux GitLab runner does not replace them.

## 7.2 Java with Gradle

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

Use the repository's Gradle Wrapper. Do not depend on an arbitrary workstation Gradle installation.

## 7.3 Java with Maven

```bash theme={null}
./mvnw --batch-mode clean verify
```

When no Maven Wrapper exists:

```bash theme={null}
mvn --batch-mode clean verify
```

Prefer adding and maintaining the Maven Wrapper for reproducibility.

## 7.4 Docker/container projects

```bash theme={null}
docker build --pull --tag local/<project>:dev .
docker run --rm local/<project>:dev <health-or-test-command>
```

CI may use approved rootless Buildah/Podman images rather than mounting the host Docker socket.

## 8. Pipeline behaviour developers should expect

Pipeline sources:

| Event | Expected jobs |
| - | - |
| Merge request | format/lint/analyse, unit tests, relevant integration tests |
| Default branch | tests, build, package as configured, deploy test environment |
| Semantic version tag | full release build, signing, immutable package publication, release candidate |
| Manual promotion | Experimental/Beta/Stable channel manifest update |
| Schedule | dependency/security/maintenance checks as configured |

A failed required job blocks merge. Do not retry until understanding whether the failure is deterministic, flaky, environmental, or a runner fault.

## 9. CI configuration ownership

Projects should consume versioned shared templates:

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

Rules:

* Pin shared templates to a version tag, not a mutable branch.
* Upgrade templates through a merge request.
* Do not copy/paste and silently fork a shared template.
* Project-specific jobs may extend templates.
* Changes to central templates require review from the CI template owner.
* Base CI images use immutable tags/digests controlled by NCV.

## 10. Environments and configuration

Standard environment names:

```text theme={null}
development/local
test
staging
production
```

Use environment-specific configuration through:

* protected/masked/file-type GitLab CI variables;
* secret manager or platform configuration;
* deployment system variables;
* non-secret checked-in defaults.

Never commit:

* `.env` containing credentials;
* production database passwords;
* API keys;
* signing certificates or private keys;
* Apple `.p8` keys;
* service-account JSON;
* private SSH keys;
* Azure PATs/service-connection secrets;
* GitLab tokens.

Provide `.env.example` containing keys and safe example values only.

## 11. CI/CD variable rules

Project variables are for project-only values. Group variables are for values genuinely shared across a defined group.

Mark a variable:

* **Masked** when its value must not print in logs;
* **Protected** when only protected refs may access it;
* **File** when a tool expects a file path, such as a certificate or key file.

A variable must not be marked protected if a normal merge-request job needs it. Instead redesign the job so untrusted/MR code cannot access the production secret.

Never echo secrets, enable shell tracing around them, or upload their containing files as artifacts.

## 12. Database migration standard

Database migrations must be classified:

* backward-compatible additive;
* long-running/online;
* coordinated breaking;
* destructive.

Preferred expand/contract sequence:

1. add new structure while old application remains compatible;
2. deploy code capable of both old and new;
3. backfill/verify data;
4. switch reads/writes;
5. remove old structure in a later release.

Every schema migration merge request must state:

* expected duration;
* lock risk;
* rollback/data implications;
* supported old/new application versions;
* test evidence on representative data.

## 13. Versioning

Use Semantic Versioning for product releases:

```text theme={null}
MAJOR.MINOR.PATCH
```

Examples:

```text theme={null}
7.2.0
7.2.1
8.0.0
```

Interpretation:

* MAJOR: incompatible customer/API/data behaviour requiring explicit migration planning;
* MINOR: backward-compatible functionality;
* PATCH: backward-compatible fixes.

Pre-release identifiers may be used for immutable candidate versions:

```text theme={null}
7.3.0-beta.1
7.3.0-rc.2
```

The NCV channel is separate from version identity. The same immutable `7.3.0+pipeline.1842` artifact can be referenced by Experimental, Beta, and Stable manifests.

## 14. Release preparation

A customer-facing release requires:

1. version agreed;
2. Jira scope fixed;
3. tests green;
4. test/UAT evidence recorded;
5. release notes completed from `templates/release-notes.md`;
6. platform packages built on approved runners;
7. binaries code-signed where applicable;
8. SHA-256 calculated;
9. immutable package uploaded;
10. GitLab Release created;
11. Experimental promotion;
12. QA/pilot evidence;
13. Beta/Stable manual promotion as approved.

Never build a separate “Stable build.” Stable must point to the exact candidate already tested.

## 15. Release notes

Release notes are written for management, support, implementers, and customers—not only developers.

Include:

* outcome and affected users;
* new functionality;
* fixes;
* operational/configuration/database changes;
* minimum compatible versions;
* verification evidence;
* known limitations;
* exact rollback version/method;
* Jira issue references.

Avoid:

```text theme={null}
misc fixes
updates
refactoring
technical changes
```

Describe observable behaviour and business impact.

## 16. Release channels

Definitions:

| Channel | Audience | Standard |
| - | - | - |
| Experimental | NCV engineering/internal test devices | newest approved candidate; may change frequently |
| Beta | QA, pilot customers/devices | passed automated tests and internal verification |
| Stable | production customers | approved release notes, UAT/pilot, rollback, signatures |

Developers do not manually edit public channel JSON on a workstation. Promotion occurs through the controlled GitLab pipeline/API job and creates an auditable commit.

## 17. Desktop updater responsibilities

The installed application/update helper should:

1. identify product/platform/architecture/current version;
2. obtain the authorized channel or rollout policy;
3. download the channel manifest over HTTPS;
4. validate schema and version;
5. apply deterministic rollout selection;
6. show release notes where appropriate;
7. download to a temporary location;
8. validate length and SHA-256;
9. validate platform code signature;
10. stage safely;
11. offer **Restart now** / **Later** where policy allows;
12. apply atomically or through a dedicated helper;
13. restart and report result;
14. retain/restore prior known-good version according to the chosen updater design.

The customer client must not contain a GitLab personal/project access token. Public release projects or a dedicated release API/CDN provide endpoint access.

## 18. Emergency fixes

For a production incident:

1. open/link the incident Jira issue;
2. create a Jira-keyed branch from the exact production tag/branch;
3. implement the smallest safe fix;
4. add regression tests;
5. run required pipeline and targeted verification;
6. use normal signed immutable package flow;
7. promote through the emergency approval path;
8. merge/cherry-pick the fix back into main where needed;
9. document incident, release, rollback and follow-up.

Emergency does not mean:

* direct editing on a production server;
* unsigned binaries sent over chat;
* replacing package files under an existing version;
* skipping audit evidence.

## 19. Common troubleshooting

### SSH says permission denied

```bash theme={null}
ssh -vvv -T git@code.naudecoreventures.com
ssh-add -l
```

Verify the key is uploaded and the correct identity is selected.

### HTTPS clone asks repeatedly for a password

Prefer SSH. If HTTPS is required, use the approved credential helper/token workflow; normal account passwords may not work where 2FA/token authentication applies.

### Pipeline is pending

Check:

* job tags versus runner tags;
* protected branch/tag requirements;
* Windows/macOS runner availability;
* whether the single Linux runner is busy;
* project permission to the shared runner.

### Package upload receives 401/403

Check:

* destination project ID;
* `CI_JOB_TOKEN` allowlist/cross-project permission;
* deploy/project token scope and expiry;
* package-registry setting;
* protected-variable availability on the ref.

### Pipeline passes locally but fails in CI

Compare:

* toolchain/runtime versions;
* case sensitivity;
* uncommitted/generated files;
* environment variables;
* timezone/locale;
* network assumptions;
* tests depending on order or machine state.

Reproduce using the same approved CI image whenever possible.

## 20. Definition of done

A work item is done only when applicable items are complete:

* acceptance criteria satisfied;
* implementation reviewed;
* unit/integration/regression tests included;
* pipeline green;
* test environment verified;
* docs/config/runbook updated;
* observability added/updated;
* security reviewed;
* database migration safe;
* release notes supplied;
* rollback documented;
* Jira and GitLab linked;
* deployment/release completed where in scope;
* support/operations notified where required.

“Code merged” is not automatically “business outcome delivered.”

## 21. Developer quick reference

```bash theme={null}
# Start work
git switch main
git pull --ff-only origin main
git switch -c JIRA-123-short-description

# Review and commit
git status
git diff
git add <files>
git diff --staged
git commit -m "JIRA-123 fix: describe the outcome"

# Update and push
git fetch origin
git rebase origin/main
git push -u origin JIRA-123-short-description

# After a safe rebase
git push --force-with-lease
```

## 22. Official references

* GitLab SSH keys: [https://docs.gitlab.com/user/ssh/](https://docs.gitlab.com/user/ssh/)
* GitLab merge requests: [https://docs.gitlab.com/user/project/merge\_requests/](https://docs.gitlab.com/user/project/merge_requests/)
* GitLab CI/CD: [https://docs.gitlab.com/ci/](https://docs.gitlab.com/ci/)
* GitLab CI variables: [https://docs.gitlab.com/ci/variables/](https://docs.gitlab.com/ci/variables/)
* GitLab protected branches: [https://docs.gitlab.com/user/project/repository/branches/protected/](https://docs.gitlab.com/user/project/repository/branches/protected/)
* GitLab Releases: [https://docs.gitlab.com/user/project/releases/](https://docs.gitlab.com/user/project/releases/)
* GitLab Generic Packages: [https://docs.gitlab.com/user/packages/generic\_packages/](https://docs.gitlab.com/user/packages/generic_packages/)
* GitLab environments: [https://docs.gitlab.com/ci/environments/](https://docs.gitlab.com/ci/environments/)


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