Backport Workflow

Example CPG workflow

This page demonstrates how to compose existing CPG tools into a backport assessment. A dedicated backport skill suite is not yet implemented — the workflow below is performed manually using individual MCP tool calls.

Apogee provides a structured backport safety assessment that combines CPG cross-branch analysis with the large-systems-change workflow. This page shows how to evaluate whether a function is safe to backport and how to execute the backport through a governed process.

Overview

Backporting a function from one branch to another is risky. The function may depend on callees that don’t exist in the target branch. Its safety profile (bounds checking, null checks, error handling) may diverge. The function body may have changed in ways that interact with the target branch’s context. Apogee’s CPG engine checks all of this structurally.

Components involved

Component

Type

Role in backport

cpg_backport_check

MCP tool

Per-function backport readiness assessment

cpg_branch_divergence_report

MCP tool

Structural divergence between source and target branches

cpg_full_audit

MCP tool

Combined security scan + divergence + backport checks

cpg_find_callees

MCP tool

Check whether the function’s dependencies exist in the target

Large-systems-change workflow

7-phase workflow

Structured patch development from scoping to upstream submission

Governance gates

Gate system

Approval enforcement at phase boundaries

End-to-end flow

Step 1 — Identify backport candidates

Start with a branch divergence report to see what changed between source and target:

cpg_branch_divergence_report(
    branch_a="rhel-9.5",
    branch_b="mainline",
    subsystem="drivers/crypto"
)

This produces a ranked list of diverged functions with body-hash comparison and safety-flag deltas. Functions with high divergence or safety changes are the ones that need backport assessment.

Step 2 — Assess backport readiness per function

For each candidate, run the backport check:

cpg_backport_check(
    function_name="crypto_aead_encrypt",
    source_branch="mainline",
    target_branch="rhel-9.5"
)

The check evaluates:

  • Existence — does the function exist in both branches?

  • Body identity — are the implementations identical (hash match)?

  • Callee compatibility — do all functions it calls exist in the target? Missing callees = prerequisites that must be backported first.

  • Safety profile — do safety flags (untrusted input, bounds check, unsafe copy, allocation, null check, error check) match? Divergence here means the function behaves differently in the target’s context.

Risk levels:

  • Critical — safety flags diverge between branches

  • High — missing prerequisites (callees not in target)

  • Medium — body differs but safety profile matches

  • Low — identical or new function (no conflict)

Step 3 — Full cross-branch audit (optional)

For comprehensive assessment, run the full audit:

cpg_full_audit(
    branch_a="mainline",
    branch_b="rhel-9.5",
    subsystem="drivers/crypto",
    mode="comprehensive"
)

This combines security scan on both branches, divergence report, and backport checks on the top 10 most diverged functions into a single report.

Step 4 — Structured patch development

When backport candidates are identified, the large-systems-change workflow provides a 7-phase governed process:

  1. Problem scoping — define the backport scope, success criteria, risk profile

  2. Structural analysis — CPG-based call graph mapping, blast radius, data flow tracing, safety profile extraction

  3. Change design — formal design with backport readiness gate (cpg_backport_check against target branches), failure modes, multi-patch decision

  4. Test baseline — capture test environment, baseline measurements, stability verification

  5. Patch implementation — code changes against design, CPG verification, safety regression check

  6. Cross-validation — five-dimension validation: cross-branch (backport checks), cross-architecture, regression, adversarial, CPG structural audit. Go/no-go decision.

  7. Upstream submission — commit messages, cover letters, reviewer identification from MAINTAINERS, submission via git-send-email or pull request

Step 5 — Governance gates

Each phase boundary has a governance gate. The gate evaluator checks conditions (tests pass, CPG audit clean, backport checks at acceptable risk level) against apogee.policy.json. Blockers halt the workflow.

Example scenario

Backporting a crypto driver fix from mainline to RHEL 9.5:

  1. cpg_branch_divergence_report shows crypto_aead_encrypt has body divergence and a safety-flag delta (bounds check added in mainline, missing in RHEL 9.5).

  2. cpg_backport_check returns risk level critical — safety divergence. Also flags that crypto_aead_setkey (a callee) was modified in mainline but not in RHEL 9.5 — prerequisite backport needed.

  3. The large-systems-change workflow Phase 3 (change design) documents the two-patch backport: crypto_aead_setkey first (prerequisite), then crypto_aead_encrypt.

  4. Phase 6 (cross-validation) re-runs cpg_backport_check after both patches are applied to confirm risk dropped to low.

  5. Phase 7 submits via git-send-email with AI attribution trailers.

When to use

  • RHEL branch maintenance — assessing which mainline fixes are safe to backport to stable branches

  • LTS kernel maintenance — checking prerequisite chains before cherry-picking

  • Any cross-branch code movement — the tools work on any repo with multiple branches, not just kernel

See also