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:2. First-day setup
2.1 Account and security
- Accept the GitLab invitation for
https://code.naudecoreventures.com. - Set a unique password stored in the approved password manager.
- Enable two-factor authentication immediately.
- Save recovery codes in the password manager, not on the workstation desktop.
- Confirm the correct NCV group/project role.
- Do not create a personal access token unless a specific workflow requires it.
2.2 Install Git and Git LFS
Ubuntu/Debian:- 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.
2.3 Configure Git identity
Use the name and email associated with the GitLab account: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:3. Repository layout and ownership
Expected group layout:- 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.
4.2 Branch naming
Use:feature/ are optional only if the repository team consistently uses them:
main:
4.3 Commit messages
Use this pattern:- 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.
5. Daily development flow
git add . without reviewing git status and git diff --staged.
After rebasing an already-pushed personal branch:
--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
6.3 Required description
Usetemplates/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:- correctness and business outcome;
- data integrity and backward compatibility;
- security and secret handling;
- test quality;
- observability and failure behaviour;
- maintainability;
- deployment and rollback;
- release-note completeness.
6.5 Merge policy
mainis protected.- Direct pushes to
mainare 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
7.2 Java with Gradle
7.3 Java with Maven
7.4 Docker/container projects
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:- 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:- protected/masked/file-type GitLab CI variables;
- secret manager or platform configuration;
- deployment system variables;
- non-secret checked-in defaults.
.envcontaining credentials;- production database passwords;
- API keys;
- signing certificates or private keys;
- Apple
.p8keys; - service-account JSON;
- private SSH keys;
- Azure PATs/service-connection secrets;
- GitLab tokens.
.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.
12. Database migration standard
Database migrations must be classified:- backward-compatible additive;
- long-running/online;
- coordinated breaking;
- destructive.
- add new structure while old application remains compatible;
- deploy code capable of both old and new;
- backfill/verify data;
- switch reads/writes;
- remove old structure in a later release.
- 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:- MAJOR: incompatible customer/API/data behaviour requiring explicit migration planning;
- MINOR: backward-compatible functionality;
- PATCH: backward-compatible fixes.
7.3.0+pipeline.1842 artifact can be referenced by Experimental, Beta, and Stable manifests.
14. Release preparation
A customer-facing release requires:- version agreed;
- Jira scope fixed;
- tests green;
- test/UAT evidence recorded;
- release notes completed from
templates/release-notes.md; - platform packages built on approved runners;
- binaries code-signed where applicable;
- SHA-256 calculated;
- immutable package uploaded;
- GitLab Release created;
- Experimental promotion;
- QA/pilot evidence;
- Beta/Stable manual promotion as approved.
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.
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:- identify product/platform/architecture/current version;
- obtain the authorized channel or rollout policy;
- download the channel manifest over HTTPS;
- validate schema and version;
- apply deterministic rollout selection;
- show release notes where appropriate;
- download to a temporary location;
- validate length and SHA-256;
- validate platform code signature;
- stage safely;
- offer Restart now / Later where policy allows;
- apply atomically or through a dedicated helper;
- restart and report result;
- retain/restore prior known-good version according to the chosen updater design.
18. Emergency fixes
For a production incident:- open/link the incident Jira issue;
- create a Jira-keyed branch from the exact production tag/branch;
- implement the smallest safe fix;
- add regression tests;
- run required pipeline and targeted verification;
- use normal signed immutable package flow;
- promote through the emergency approval path;
- merge/cherry-pick the fix back into main where needed;
- document incident, release, rollback and follow-up.
- 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
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_TOKENallowlist/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.
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.
21. Developer quick reference
22. Official references
- GitLab SSH keys: https://docs.gitlab.com/user/ssh/
- GitLab merge requests: https://docs.gitlab.com/user/project/merge_requests/
- GitLab CI/CD: https://docs.gitlab.com/ci/
- GitLab CI variables: https://docs.gitlab.com/ci/variables/
- GitLab protected branches: https://docs.gitlab.com/user/project/repository/branches/protected/
- GitLab Releases: https://docs.gitlab.com/user/project/releases/
- GitLab Generic Packages: https://docs.gitlab.com/user/packages/generic_packages/
- GitLab environments: https://docs.gitlab.com/ci/environments/