Skip to main content

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

2.3 Configure Git identity

Use the name and email associated with the GitLab account:
Review:
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:
Load it:
Copy the public key:
Add it in GitLab under Edit profile > Access > SSH keys. Never upload the private key. Optional SSH config:
Test:
Clone:

3. Repository layout and ownership

Expected group layout:
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:
Examples:
Prefixes such as feature/ are optional only if the repository team consistently uses them:
The Jira key is mandatory. Create from current main:

4.3 Commit messages

Use this pattern:
Recommended types:
Examples:
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:

5. Daily development flow

Do not use git add . without reviewing git status and git diff --staged. After rebasing an already-pushed personal branch:
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

Example:

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

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

7.2 Java with Gradle

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

7.3 Java with Maven

When no Maven Wrapper exists:
Prefer adding and maintaining the Maven Wrapper for reproducibility.

7.4 Docker/container projects

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

8. Pipeline behaviour developers should expect

Pipeline sources: 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:
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:
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:
Examples:
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:
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:
Describe observable behaviour and business impact.

16. Release channels

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

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

22. Official references