Skip to content

Package Backports

Jump to bottom
Andrew Kroh edited this page Aug 6, 2026 · 1 revision

Some packages keep one or more backport branches alongside main. This page explains why those branches exist, and which changes belong on them.

Table of Contents

Do I need to backport this change?

Backport the change if it corrects behavior that the backport branch already has. Leave it on main if it adds new behavior.

Tick the box when your change is one of these:

  • A fix to an ingest pipeline, a mapping, or a field definition.
  • A fix to data collection, for example a broken API path or a pagination bug.
  • A security fix.
  • A change that keeps the package working on the older stack.

Leave the box clear when your change is one of these:

  • A new data stream, a new input, a new dashboard, or new field coverage.
  • A refactor, a cleanup, or a dependency bump that no fix requires.
  • A change to a data stream that does not exist on that branch.
  • A test-only or build-only change.

Read How to decide for the borderline cases. Read Why backport branches exist if you want the reasoning.

Why backport branches exist

A backport branch lets you serve two audiences from one package. Users on the current stack get the new features. Users on an older, still supported stack keep getting fixes.

Users stay on older stack versions

Elastic maintains each major release for the longer of 30 months from its own GA, or 18 months from the GA of the next major. Version 8.x is in maintenance until 15 January 2027, and support continues for six months after that. See the Elastic product end of life dates.

Many users take months or years to upgrade. A user who runs 8.19 today expects package fixes until 8.x maintenance ends. Package releases are independent of stack releases, so a user on 8.19 receives new package versions from the Elastic Package Registry (EPR) at any time. Backports keep that channel open.

What puts a package version out of reach

EPR serves each user the newest package version their stack can install. A backport branch becomes necessary when the newest version on main no longer reaches a stack that we still support. Several changes cause that.

  • A higher format_version. This field declares which package-spec version the package uses. Kibana installs only the spec versions it understands, so each spec version sets a floor on the stack versions that can install the package.
  • A narrower conditions.kibana.version. The package states a minimum stack version directly.
  • A package that pins itself to a stack minor by design. The security_detection_engine package keeps one branch per supported minor, because its rules target a specific stack version.
  • A breaking change inside the package that we do not want to send to users on the older stack.

The format version floors are:

format_version Supported stack versions
3.0 all versions
3.1 - 3.3 8.16 and later
3.4 8.19, and 9.1 and later
3.5 9.2 and later
3.6 9.4 and later

See Guidelines for the format version to use in a package for the current table.

Users below the floor see no error. They keep the last compatible version, and they stop receiving fixes. Nothing in the Fleet UI tells them why. A backport branch is how you continue to ship fixes to them.

Example: the AWS package

The AWS package needed var_groups to present a credential type selector for identity federation. That feature requires format_version 3.5 or later, and the package moved to 3.6. Kibana 8.19 caps at spec 3.4.

We had two options. The first was to hold the feature until 8.x maintenance ends in January 2027. That blocks every AWS data stream from adopting the newer spec for months. The second was to raise the format version and maintain a backport branch that carries fixes to 8.19 users through the maintenance term. We chose the second.

The same conflict returns whenever a supported minor version caps below the spec version that a feature requires. The move to 3.6 also excluded 9.2 and 9.3.

What to backport

Treat a backport branch as a bug fix line. Its feature set stays where it was at the fork point. It keeps the older stack working. It does not reach feature parity with main.

Backport these changes

  • Ingest pipeline fixes. Wrong field mappings, failed parsing, incorrect timestamps, missing ECS normalization, broken conditionals.
  • Collection fixes. A broken API path, a pagination bug, a cursor that skips events, an authentication call that stopped working.
  • Security fixes. Anything that leaks a credential or logs sensitive data.
  • Compatibility fixes. A change needed to keep the package working on the older stack, for example an upstream API change or a deprecated Elasticsearch processor option.
  • Documentation corrections for behavior that exists on the branch.

Do not backport these changes

  • New data streams.
  • New inputs, or a new input type for an existing data stream.
  • New fields that add coverage the branch never had.
  • New dashboards, and new visualizations on existing dashboards.
  • Refactors, cleanups, and dependency bumps that no fix requires.
  • Anything that needs a spec version the older stack cannot install. The branch exists because that code path does not run there.

How to decide

Ask one question. Does this change correct behavior that is already on the branch, or does it add behavior?

A fix that adds a field can still be a backport. If a pipeline drops a value that the branch already parses, and the fix maps it correctly, backport it. If the field comes from a new API call or a new event type, leave it on main.

If a fix needs a different shape on the older branch, do not force the cherry-pick. Open a separate PR against the branch.

Before you raise the format version

  1. Check the format version table. Choose the lowest spec version that provides the features you need. A lower floor means fewer users need the backport branch.
  2. Find the maintenance date for the versions you exclude on the EOL page. That date is how long the branch lives. Record it as maintained_until in .backports.yml.
  3. Name the team that maintains the branch. The package owners hold it by default. Get that agreement before you merge.
  4. Narrow conditions.kibana.version in the manifest to the new floor, so that the constraint states the same thing as the spec version.
  5. Bump the package major version in the release that raises the floor. The fork point takes the major bump, so the backport branch keeps enough minor and patch numbers for its lifetime.
  6. Add a changelog entry that records the new stack floor, and a README note for users on the older stack.

The backport inventory

.backports.yml in the repository root lists every backport branch. Each entry records the package, the branch, the base version, the base commit, and the maintained_until date. A branch stops appearing in the checklist once that date passes, or once someone sets archived: true.

For the branch creation and release steps, see Release a bug fix for supporting older package version.

References

Clone this wiki locally