[management] Document mutual exclusivity of policy rule ports and port_ranges (#7158)

Prepares the repository for the release-branch process agreed internally:
one long-lived release-0.N branch per minor, with fixes backported by
cherry-pick and patch releases tagged from the branch.

Pushes to release-* branches now run the Release workflow and publish
immutable sha-* container images, the way pushes to main already do, so
a release branch can be tested before it is tagged. Release branches
never publish the floating "main" image tag. The push-to-main CI
workflows (Go tests on all platforms, frontend UI, install script,
mobile/wasm validation, infrastructure files, license check) also run
on release-* pushes; pull request triggers were already unfiltered, so
backport PRs were covered — this closes the post-merge gap.

Releases are no longer marked latest before signing: make_latest is
now false in all four goreleaser configs, so a release stays published
but not latest until the signing pipeline uploads the signed Windows
and macOS artifacts and marks it latest itself. Previously the release
became GitHub's "Latest release" at publish time, and the download
endpoints that resolve through the latest-release API could serve a
release whose signed installers did not exist yet. prerelease: auto
additionally labels rc tags as prereleases, so a release candidate can
never take the latest slot.

The trigger_sync_tag job is removed: it dispatched a downstream
image build on every v* tag (release candidates included), which would
race the deliberate release-branch build on every release. The android
and ios submodule bumps are unchanged.

Also sets perennial-regex = "^release-" so git-town never syncs or
ships a release branch into main.

.git-branches.toml

@@ -3,7 +3,7 @@
 [branches]
 main = "main"
 perennials = []
-perennial-regex = ""
+perennial-regex = "^release-"
 
 [create]
 new-branch-type = "feature"

.github/workflows/check-license-dependencies.yml

@@ -2,7 +2,7 @@ name: Check License Dependencies
 
 on:
   push:
-    branches: [main]
+    branches: [main, "release-*"]
     paths:
       - "go.mod"
       - "go.sum"

.github/workflows/frontend-ui.yml

@@ -10,6 +10,7 @@ on:
   push:
     branches:
       - main
+      - "release-*"
     paths:
       - "client/ui/frontend/**"
       - "client/ui/i18n/**"

.github/workflows/golang-test-darwin.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - "release-*"
   pull_request:
 
 concurrency:

.github/workflows/golang-test-freebsd.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - "release-*"
   pull_request:
 
 concurrency:

.github/workflows/golang-test-linux.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - "release-*"
   pull_request:
 
 concurrency:

.github/workflows/golang-test-windows.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - "release-*"
   pull_request:
 
 env:

.github/workflows/install-script-test.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - "release-*"
   pull_request:
     paths:
       - "release_files/install.sh"

.github/workflows/mobile-build-validation.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - "release-*"
   pull_request:
 
 concurrency:

.github/workflows/release.yml

@@ -6,6 +6,7 @@ on:
       - "v*"
     branches:
       - main
+      - "release-*"
   pull_request:
 
 env:
@@ -254,15 +255,23 @@ jobs:
         id: tag_and_push_images
         if: |
           (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) ||
-          (github.event_name == 'push' && github.ref == 'refs/heads/main')
+          (github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release-')))
         run: |
           set -euo pipefail
 
+          # $GITHUB_REF / $GITHUB_EVENT_NAME are read from the runner
+          # environment rather than substituted into this script with the
+          # workflow expression syntax: branch names may legally contain
+          # $(…), and interpolating github.ref would execute it.
           resolve_tags() {
-            if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            if [[ "$GITHUB_EVENT_NAME" == "pull_request" ]]; then
               echo "pr-${{ github.event.pull_request.number }}"
-            else
+            elif [[ "$GITHUB_REF" == "refs/heads/main" ]]; then
               echo "main sha-$(git rev-parse --short HEAD)"
+            else
+              # Release branches get an immutable sha-* tag only — the floating
+              # "main" tag must never move from a release branch.
+              echo "sha-$(git rev-parse --short HEAD)"
             fi
           }
 

.github/workflows/sync-tag.yml

@@ -9,21 +9,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}-${{ github.head_ref || github.actor_id }}
   cancel-in-progress: true
 
-# Receiving workflows (cloud sync-tag, mobile bump-netbird) expect the short
-# tag form (e.g. v0.30.0), not refs/tags/v0.30.0 — github.ref_name, not github.ref.
+# The receiving bump-netbird workflows expect the short tag form
+# (e.g. v0.30.0), not refs/tags/v0.30.0 — github.ref_name, not github.ref.
 jobs:
-  trigger_sync_tag:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Trigger release tag sync
-        uses: benc-uk/workflow-dispatch@31e2b3319479a63f0ab15bf800eff9e913504e26 # v1.3.2
-        with:
-          workflow: sync-tag.yml
-          ref: main
-          repo: ${{ secrets.UPSTREAM_REPO }}
-          token: ${{ secrets.NC_GITHUB_TOKEN }}
-          inputs: '{ "tag": "${{ github.ref_name }}" }'
-
   trigger_android_bump:
     runs-on: ubuntu-latest
     if: github.event.created && !github.event.deleted && startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-')

.github/workflows/test-infrastructure-files.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - "release-*"
   pull_request:
     paths:
       - "infrastructure_files/**"

.github/workflows/wasm-build-validation.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - "release-*"
   pull_request:
 
 concurrency:

.goreleaser.yaml

@@ -468,6 +468,13 @@ checksum:
     - glob: ./infrastructure_files/migrate-to-enterprise.sh
 
 release:
+  # The signing pipeline (netbirdio/sign-pipelines, dispatched by
+  # trigger_signer) marks the release latest once the Windows and macOS
+  # artifacts are signed. Without this override goreleaser marks it latest
+  # at publish time, while those artifacts are still unsigned.
+  make_latest: false
+  # Mark x.y.z-rc.* and other prerelease tags as prereleases on GitHub.
+  prerelease: auto
   extra_files:
     - glob: ./infrastructure_files/getting-started-with-zitadel.sh
     - glob: ./release_files/install.sh

.goreleaser_ui.yaml

@@ -144,3 +144,11 @@ uploads:
     target: https://pkgs.wiretrustee.com/yum/{{ .Arch }}{{ if .Arm }}{{ .Arm }}{{ end }}
     username: dev@wiretrustee.com
     method: PUT
+
+release:
+  # Uploads into the release created by the main .goreleaser.yaml run.
+  # make_latest stays false everywhere: the signing pipeline
+  # (netbirdio/sign-pipelines) marks the release latest after the Windows
+  # and macOS artifacts are signed.
+  make_latest: false
+  prerelease: auto

.goreleaser_ui_darwin.yaml

@@ -43,3 +43,11 @@ checksum:
   name_template: "{{ .ProjectName }}_darwin_checksums.txt"
 changelog:
   disable: true
+
+release:
+  # Uploads into the release created by the main .goreleaser.yaml run.
+  # make_latest stays false everywhere: the signing pipeline
+  # (netbirdio/sign-pipelines) marks the release latest after the Windows
+  # and macOS artifacts are signed.
+  make_latest: false
+  prerelease: auto

.goreleaser_ui_gtk3.yaml

@@ -134,3 +134,11 @@ uploads:
     target: https://pkgs.wiretrustee.com/yum/{{ .Arch }}{{ if .Arm }}{{ .Arm }}{{ end }}
     username: dev@wiretrustee.com
     method: PUT
+
+release:
+  # Uploads into the release created by the main .goreleaser.yaml run.
+  # make_latest stays false everywhere: the signing pipeline
+  # (netbirdio/sign-pipelines) marks the release latest after the Windows
+  # and macOS artifacts are signed.
+  make_latest: false
+  prerelease: auto

client/installer.nsis

@@ -22,8 +22,6 @@
 !define UI_REG_APP_PATH "Software\Microsoft\Windows\CurrentVersion\App Paths\${UI_APP_EXE}"
 !define UI_UNINSTALL_PATH "Software\Microsoft\Windows\CurrentVersion\Uninstall\${UI_APP_NAME}"
 
-!define AUTOSTART_REG_KEY "Software\Microsoft\Windows\CurrentVersion\Run"
-
 !define NETBIRD_DATA_DIR "$COMMONPROGRAMDATA\Netbird"
 
 Unicode True
@@ -228,13 +226,6 @@ WriteRegStr ${REG_ROOT} "${UNINSTALL_PATH}"  "Publisher" "${COMP_NAME}"
 
 WriteRegStr ${REG_ROOT} "${UI_REG_APP_PATH}" "" "$INSTDIR\${UI_APP_EXE}"
 
-; Autostart is owned by the UI's per-user setting (HKCU\...\Run via Wails),
-; not the installer. Drop the machine-wide entry older installers wrote so the
-; toggle is the single source of truth. HKCU is left untouched -- it may hold
-; the user's own toggle state, which must survive upgrades.
-DetailPrint "Removing installer-managed autostart registry entry if present..."
-DeleteRegValue HKLM "${AUTOSTART_REG_KEY}" "${APP_NAME}"
-
 EnVar::SetHKLM
 EnVar::AddValueEx "path" "$INSTDIR"
 
@@ -299,15 +290,6 @@ ExecWait '"$INSTDIR\${MAIN_APP_EXE}" service uninstall'
 DetailPrint "Terminating Netbird UI process..."
 ExecWait `taskkill /im ${UI_APP_EXE}.exe /f`
 
-; Remove autostart registry entries
-DetailPrint "Removing autostart registry entries if they exist..."
-; Legacy machine-wide entry written by older installers.
-DeleteRegValue HKLM "${AUTOSTART_REG_KEY}" "${APP_NAME}"
-; Per-user entry the UI toggle writes via Wails (value name is the lowercase
-; app-name slug). Uninstall removes the app, so drop it too.
-DeleteRegValue HKCU "${AUTOSTART_REG_KEY}" "${APP_NAME}"
-DeleteRegValue HKCU "${AUTOSTART_REG_KEY}" "netbird"
-
 ; Handle data deletion based on checkbox
 DetailPrint "Checking if user requested data deletion..."
 ${If} $DeleteDataEnabled == "1"

shared/management/http/api/openapi.yml

@@ -1433,13 +1433,14 @@ components:
           enum: [ "all", "tcp", "udp", "icmp", "netbird-ssh" ]
           example: "tcp"
         ports:
-          description: Policy rule affected ports
+          description: Policy rule affected ports. Mutually exclusive with `port_ranges`. A rule accepts either individual ports or port ranges, not both.
+          x-omit-from-example: true
           type: array
           items:
             type: string
             example: "80"
         port_ranges:
-          description: Policy rule affected ports ranges list
+          description: Policy rule affected ports ranges list. Mutually exclusive with `ports`. To mix individual ports with ranges in one rule, express each single port as a range with identical start and end values (for example, start 443, end 443).
           type: array
           items:
             $ref: '#/components/schemas/RulePortRange'
@@ -1459,7 +1460,7 @@ components:
         - action
 
     RulePortRange:
-      description: Policy rule affected ports range
+      description: Policy rule affected ports range. A range with identical start and end values represents a single port.
       type: object
       properties:
         start:

shared/management/http/api/types.gen.go

@@ -4468,10 +4468,10 @@ type PolicyRule struct {
 	// Name Policy rule name identifier
 	Name string `json:"name"`
 
-	// PortRanges Policy rule affected ports ranges list
+	// PortRanges Policy rule affected ports ranges list. Mutually exclusive with `ports`. To mix individual ports with ranges in one rule, express each single port as a range with identical start and end values (for example, start 443, end 443).
 	PortRanges *[]RulePortRange `json:"port_ranges,omitempty"`
 
-	// Ports Policy rule affected ports
+	// Ports Policy rule affected ports. Mutually exclusive with `port_ranges`. A rule accepts either individual ports or port ranges, not both.
 	Ports *[]string `json:"ports,omitempty"`
 
 	// Protocol Policy rule type of the traffic
@@ -4508,10 +4508,10 @@ type PolicyRuleMinimum struct {
 	// Name Policy rule name identifier
 	Name string `json:"name"`
 
-	// PortRanges Policy rule affected ports ranges list
+	// PortRanges Policy rule affected ports ranges list. Mutually exclusive with `ports`. To mix individual ports with ranges in one rule, express each single port as a range with identical start and end values (for example, start 443, end 443).
 	PortRanges *[]RulePortRange `json:"port_ranges,omitempty"`
 
-	// Ports Policy rule affected ports
+	// Ports Policy rule affected ports. Mutually exclusive with `port_ranges`. A rule accepts either individual ports or port ranges, not both.
 	Ports *[]string `json:"ports,omitempty"`
 
 	// Protocol Policy rule type of the traffic
@@ -4551,10 +4551,10 @@ type PolicyRuleUpdate struct {
 	// Name Policy rule name identifier
 	Name string `json:"name"`
 
-	// PortRanges Policy rule affected ports ranges list
+	// PortRanges Policy rule affected ports ranges list. Mutually exclusive with `ports`. To mix individual ports with ranges in one rule, express each single port as a range with identical start and end values (for example, start 443, end 443).
 	PortRanges *[]RulePortRange `json:"port_ranges,omitempty"`
 
-	// Ports Policy rule affected ports
+	// Ports Policy rule affected ports. Mutually exclusive with `port_ranges`. A rule accepts either individual ports or port ranges, not both.
 	Ports *[]string `json:"ports,omitempty"`
 
 	// Protocol Policy rule type of the traffic
@@ -4962,7 +4962,7 @@ type RouteRequest struct {
 	SkipAutoApply *bool `json:"skip_auto_apply,omitempty"`
 }
 
-// RulePortRange Policy rule affected ports range
+// RulePortRange Policy rule affected ports range. A range with identical start and end values represents a single port.
 type RulePortRange struct {
 	// End The ending port of the range
 	End int `json:"end"`