Factor branch parsing logic

Add shared branch family/suite resolver script.

Reuse it in pkg-build and pkg-release workflows.

Update docs for last-two-segments parsing rule.

Signed-off-by: Simon Beaudoin <sbeaudoi@qti.qualcomm.com>

Author: simonbeaudoin0935

.github/workflows/pkg-build-reusable-workflow.yml

@@ -123,6 +123,13 @@ jobs:
       force_docker_build: ${{ steps.resolve.outputs.force_docker_build }}
       suite: ${{ steps.resolve.outputs.suite }}
     steps:
+      - name: Checkout qcom-build-utils scripts
+        uses: actions/checkout@v5
+        with:
+          repository: qualcomm-linux/qcom-build-utils
+          ref: ${{ inputs.qcom-build-utils-ref }}
+          path: qcom-build-utils
+
       - name: Resolve family and suite from branch
         id: resolve
         shell: bash
@@ -134,61 +141,40 @@ jobs:
         run: |
           set -euo pipefail
 
-          normalize_ref() {
-            local ref="$1"
-            if [[ "$ref" == refs/heads/* ]]; then
-              ref="${ref#refs/heads/}"
-            fi
-            if [[ "$ref" == refs/remotes/* ]]; then
-              ref="${ref#refs/remotes/}"
-            fi
-            if [[ "$ref" == origin/* ]]; then
-              ref="${ref#origin/}"
-            fi
-            printf '%s\n' "$ref"
+          RESOLVER_SCRIPT="${GITHUB_WORKSPACE}/qcom-build-utils/scripts/resolve_branch_family_suite.sh"
+
+          parse_resolved_values() {
+            local resolved_kv="$1"
+            local key value
+
+            normalized_ref=""
+            family=""
+            suite=""
+            while IFS='=' read -r key value; do
+              case "$key" in
+                normalized_ref) normalized_ref="$value" ;;
+                family) family="$value" ;;
+                suite) suite="$value" ;;
+              esac
+            done <<< "$resolved_kv"
           }
 
-          resolve_from_ref() {
-            local ref="$1"
-            local -n out_family="$2"
-            local -n out_suite="$3"
-            local -a ref_parts
-
-            IFS='/' read -r -a ref_parts <<< "$ref"
-            if (( ${#ref_parts[@]} < 3 )); then
-              return 1
-            fi
-
-            local family_idx suite_idx
-            family_idx=$((${#ref_parts[@]} - 2))
-            suite_idx=$((${#ref_parts[@]} - 1))
-            out_family="${ref_parts[$family_idx]}"
-            out_suite="${ref_parts[$suite_idx]}"
-
-            case "$out_family" in
-              debian|ubuntu)
-                return 0
-                ;;
-              *)
-                return 1
-                ;;
-            esac
-          }
-
-          normalized_ref="$(normalize_ref "$DEBIAN_REF_INPUT")"
-          source_ref="$normalized_ref"
-          if ! resolve_from_ref "$normalized_ref" family suite; then
+          source_ref=""
+          if resolved_kv="$("$RESOLVER_SCRIPT" "$DEBIAN_REF_INPUT")"; then
+            parse_resolved_values "$resolved_kv"
+            source_ref="$normalized_ref"
+          else
             if [[ -n "$BASE_REF_INPUT" ]]; then
-              normalized_base_ref="$(normalize_ref "$BASE_REF_INPUT")"
-              if resolve_from_ref "$normalized_base_ref" family suite; then
-                source_ref="$normalized_base_ref"
-                echo "::warning::debian-ref '$DEBIAN_REF_INPUT' does not match '<prefix>/<family>/<suite>'; falling back to base-ref '$BASE_REF_INPUT' for suite routing."
+              if resolved_kv="$("$RESOLVER_SCRIPT" "$BASE_REF_INPUT")"; then
+                parse_resolved_values "$resolved_kv"
+                source_ref="$normalized_ref"
+                echo "::warning::debian-ref '$DEBIAN_REF_INPUT' does not end with '/<family>/<suite>'; falling back to base-ref '$BASE_REF_INPUT' for suite routing."
               else
-                echo "::error::Unable to resolve build target from debian-ref '$DEBIAN_REF_INPUT' or base-ref '$BASE_REF_INPUT'. Expected '<prefix>/<family>/<suite>' such as 'qcom/ubuntu/resolute'."
+                echo "::error::Unable to resolve build target from debian-ref '$DEBIAN_REF_INPUT' or base-ref '$BASE_REF_INPUT'. Expected a branch ending in '/<family>/<suite>' (for example 'ubuntu/resolute' or 'qcom/ubuntu/resolute')."
                 exit 1
               fi
             else
-              echo "::error::Unable to resolve build target from debian-ref '$DEBIAN_REF_INPUT'. Expected '<prefix>/<family>/<suite>' such as 'qcom/ubuntu/resolute'."
+              echo "::error::Unable to resolve build target from debian-ref '$DEBIAN_REF_INPUT'. Expected a branch ending in '/<family>/<suite>' (for example 'ubuntu/resolute' or 'qcom/ubuntu/resolute')."
               exit 1
             fi
           fi

.github/workflows/pkg-release-reusable-workflow.yml

@@ -67,61 +67,37 @@ jobs:
       run:
         shell: bash
     steps:
+      - name: Checkout qcom-build-utils scripts
+        uses: actions/checkout@v5
+        with:
+          repository: qualcomm-linux/qcom-build-utils
+          ref: ${{ inputs.qcom-build-utils-ref }}
+          path: qcom-build-utils
+
       - name: Resolve family and suite from branch
         id: resolve
         env:
           DEBIAN_REF_INPUT: ${{ inputs.debian-branch }}
         run: |
           set -euo pipefail
 
-          normalize_ref() {
-            local ref="$1"
-            if [[ "$ref" == refs/heads/* ]]; then
-              ref="${ref#refs/heads/}"
-            fi
-            if [[ "$ref" == refs/remotes/* ]]; then
-              ref="${ref#refs/remotes/}"
-            fi
-            if [[ "$ref" == origin/* ]]; then
-              ref="${ref#origin/}"
-            fi
-            printf '%s\n' "$ref"
-          }
-
-          resolve_from_ref() {
-            local ref="$1"
-            local -n out_family="$2"
-            local -n out_suite="$3"
-            local -a ref_parts
-
-            IFS='/' read -r -a ref_parts <<< "$ref"
-            if (( ${#ref_parts[@]} < 3 )); then
-              return 1
-            fi
-
-            local family_idx suite_idx
-            family_idx=$((${#ref_parts[@]} - 2))
-            suite_idx=$((${#ref_parts[@]} - 1))
-            out_family="${ref_parts[$family_idx]}"
-            out_suite="${ref_parts[$suite_idx]}"
-
-            case "$out_family" in
-              debian|ubuntu)
-                return 0
-                ;;
-              *)
-                return 1
-                ;;
-            esac
-          }
-
-          normalized_ref="$(normalize_ref "$DEBIAN_REF_INPUT")"
-
-          if ! resolve_from_ref "$normalized_ref" family suite; then
-            echo "::error::Unable to resolve release target from debian-branch '$DEBIAN_REF_INPUT'. Expected '<prefix>/<family>/<suite>' such as 'qcom/ubuntu/resolute'."
+          RESOLVER_SCRIPT="${GITHUB_WORKSPACE}/qcom-build-utils/scripts/resolve_branch_family_suite.sh"
+          if ! resolved_kv="$("$RESOLVER_SCRIPT" "$DEBIAN_REF_INPUT")"; then
+            echo "::error::Unable to resolve release target from debian-branch '$DEBIAN_REF_INPUT'. Expected a branch ending in '/<family>/<suite>' (for example 'ubuntu/resolute' or 'qcom/ubuntu/resolute')."
             exit 1
           fi
 
+          normalized_ref=""
+          family=""
+          suite=""
+          while IFS='=' read -r key value; do
+            case "$key" in
+              normalized_ref) normalized_ref="$value" ;;
+              family) family="$value" ;;
+              suite) suite="$value" ;;
+            esac
+          done <<< "$resolved_kv"
+
           if [[ "$family" == "debian" ]] && [[ "$suite" == "latest" || "$suite" == "unstable" ]]; then
             suite=sid
           fi

AGENTS.md

@@ -40,7 +40,7 @@ orchestration around build, test, promotion, and release flows.
 ## Build Branch Convention (Caller Contract)
 
 For `pkg-build-reusable-workflow.yml`, callers should pass a `debian-ref` branch
-name that ends with:
+name where the last two `/`-delimited fields are:
 
 - `<family>/<suite>`
 
@@ -54,6 +54,15 @@ Examples:
 - `qcom/debian/latest` (normalized to suite `sid`)
 - `qcom/debian/bookworm`
 - `qcom/ubuntu/resolute`
+- `test/qcom/ubuntu/resolute`
+- `ubuntu/resolute`
+- `dev/whatever/yo/debian/trixie`
+
+Invalid examples:
+
+- `resolute`
+- `ubuntu`
+- `ubuntu-resolute`
 
 `pkg-build-reusable-workflow.yml` no longer takes a separate `suite` input for
 routing; it resolves family/suite from `debian-ref`.

README.md

@@ -86,16 +86,25 @@ Package repositories call these workflows from their own `.github/workflows/` di
 `pkg-build-reusable-workflow.yml` now resolves `family` and `suite` from the
 `debian-ref` branch name instead of taking a separate `suite` input.
 
-Expected branch pattern:
+Branch parsing rule:
 
-- `<prefix>/<family>/<suite>`
+- take the last two `/`-delimited fields as `<family>/<suite>`
 - `family` must be `debian` or `ubuntu`
 
 Examples:
 
 - `qcom/debian/latest` (maps to `sid`)
 - `qcom/debian/bookworm`
 - `qcom/ubuntu/resolute`
+- `test/qcom/ubuntu/resolute`
+- `ubuntu/resolute`
+- `dev/whatever/yo/debian/trixie`
+
+Invalid examples:
+
+- `resolute`
+- `ubuntu`
+- `ubuntu-resolute`
 
 For PR jobs that build transient heads (for example `debian/pr/*`), workflow
 routing falls back to the PR base branch (`github.base_ref`).

docs/reusable-workflows.md

@@ -69,6 +69,25 @@ flowchart TD
 | `srcpkg_name` | Source package name |
 | `srcpkg_version` | Source package version |
 
+### Branch Parsing Rule (`debian-ref`)
+
+- The resolver splits the normalized branch name on `/`.
+- It takes the last two fields as `<family>/<suite>`.
+- `family` must be `debian` or `ubuntu`.
+
+Valid examples:
+
+- `qcom/ubuntu/resolute` -> `family=ubuntu`, `suite=resolute`
+- `test/qcom/ubuntu/resolute` -> `family=ubuntu`, `suite=resolute`
+- `ubuntu/resolute` -> `family=ubuntu`, `suite=resolute`
+- `dev/whatever/yo/debian/trixie` -> `family=debian`, `suite=trixie`
+
+Invalid examples:
+
+- `resolute`
+- `ubuntu`
+- `ubuntu-resolute`
+
 ### Workflow Steps
 
 1. **Resolve suite family**: Normalize the caller input and decide whether the run is Debian or Ubuntu
@@ -135,6 +154,10 @@ flowchart TD
 | `test-run` | boolean | No | `true` | Debian: stop after Debusine build/test. Ubuntu: still stateful, but upload to test/proposed destination based on this input |
 | `debusine-parent-workspace` | string | No | `ci` | Parent Debusine workspace passed through to the Debian build/test phase |
 
+`debian-branch` uses the same parsing rule as `debian-ref` in the build
+reusable workflow: split on `/`, take the last two fields as
+`<family>/<suite>`, and require `family` to be `debian` or `ubuntu`.
+
 ### Secrets
 
 | Secret | Required | Description |

scripts/README.md

@@ -132,6 +132,28 @@ Shell script for merging upstream changes into Debian packaging branch.
 ./scripts/merge_debian_packaging_upstream upstream/main
 ```
 
+### 4. resolve_branch_family_suite.sh
+
+Helper used by reusable workflows to resolve `family`/`suite` from branch-like refs.
+
+**Rule:**
+- Normalize refs like `refs/heads/*`, `refs/remotes/*`, and `origin/*`
+- Split by `/`
+- Take the last two fields as `<family>/<suite>`
+- Require `family` to be `debian` or `ubuntu`
+
+**Usage:**
+```bash
+./scripts/resolve_branch_family_suite.sh <ref>
+```
+
+**Output:**
+```text
+normalized_ref=<normalized-ref>
+family=<debian|ubuntu>
+suite=<suite>
+```
+
 ## Common Workflows
 
 ### Building a Single Package

scripts/resolve_branch_family_suite.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Resolve distro family/suite from a branch-like ref.
+# The last two '/'-delimited fields are interpreted as "<family>/<suite>".
+
+set -euo pipefail
+
+normalize_ref() {
+  local ref="$1"
+
+  if [[ "$ref" == refs/heads/* ]]; then
+    ref="${ref#refs/heads/}"
+  fi
+  if [[ "$ref" == refs/remotes/* ]]; then
+    ref="${ref#refs/remotes/}"
+  fi
+  if [[ "$ref" == origin/* ]]; then
+    ref="${ref#origin/}"
+  fi
+
+  printf '%s\n' "$ref"
+}
+
+resolve_from_ref() {
+  local ref="$1"
+  local -n out_family="$2"
+  local -n out_suite="$3"
+  local -a ref_parts
+
+  IFS='/' read -r -a ref_parts <<< "$ref"
+  if (( ${#ref_parts[@]} < 2 )); then
+    return 1
+  fi
+
+  out_family="${ref_parts[$((${#ref_parts[@]} - 2))]}"
+  out_suite="${ref_parts[$((${#ref_parts[@]} - 1))]}"
+
+  case "$out_family" in
+    debian|ubuntu)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+main() {
+  if (( $# != 1 )); then
+    echo "Usage: $0 <ref>" >&2
+    exit 2
+  fi
+
+  local input_ref="$1"
+  local normalized_ref family suite
+
+  normalized_ref="$(normalize_ref "$input_ref")"
+  if ! resolve_from_ref "$normalized_ref" family suite; then
+    exit 1
+  fi
+
+  printf 'normalized_ref=%s\n' "$normalized_ref"
+  printf 'family=%s\n' "$family"
+  printf 'suite=%s\n' "$suite"
+}
+
+main "$@"