Skip to content

backport: introduce .backports.yml inventory and active-branch check script #19210

New issue
New issue
Closed
#19362
Closed
backport: introduce .backports.yml inventory and active-branch check script#19210
#19362
Assignees
mrodm
Labels
Team:EcosystemPackages Ecosystem team [elastic/ecosystem]

Description

@mrodm
mrodm
opened on May 26, 2026

Summary

Introduce .backports.yml as the single source of truth for which backport branches exist and which are active. Add backport_check_active.sh to evaluate branch status, and a one-time bootstrap script to seed the inventory from existing branches. This is the foundation that all other backport automation reads from — no other backport tooling issue should start implementation until this is merged.

Background

There is currently no structured record of which backport branches are active, which are still maintained, and which have been abandoned. Without this, automation cannot reliably discover the right target branches, and dead branches risk being accidentally targeted.

Deliverables

.backports.yml (repo root)

Single source of truth for the backport branch inventory. Schema:

backports:
  - package: aws
    branch: backport-aws-6.14
    base_version: 6.14.2
    base_commit: "cd8d67e56e"
    maintained_until: "2027-01-15"   # 8.19 EOL
    archived: false
  - package: aws
    branch: backport-aws-3.17
    base_version: 3.17.0
    base_commit: "5b593f6681"
    maintained_until: null
    archived: false

Active branch logic: a branch is inactive if archived: true OR (maintained_until != null AND maintained_until < today). Both maintained_until and archived are complementary: maintained_until handles known-deadline expiry automatically; archived handles explicit early abandonment.

dev/scripts/backport_check_active.sh

Reads .backports.yml and evaluates whether a given branch is active.

Flags: --branch <branch-name>, --json
Exit codes: 0 = active, 1 = inactive

{
  "branch": "backport-aws-6.14",
  "active": true,
  "archived": false,
  "maintained_until": "2027-01-15"
}

Bootstrap script (one-time)

Seeds .backports.yml from existing branches:

  • git ls-remote --heads origin 'backport-*' to enumerate all existing branches
  • Branches with last commit older than one year default to archived: true
  • Requires a manual review pass to fill in known maintained_until dates (e.g. 8.19 EOL → 2027-01-15)

Considerations

  • Nested package directories: the package field stores the package name as it appears in manifest.yml. The repository supports both a flat structure (packages/<package>) and a nested structure (packages/<technology>/<package>). All scripts that need the filesystem path to a package must resolve it dynamically from the name rather than assuming a flat layout. Investigate whether mage listPackages or an equivalent helper already provides a name → path mapping, or whether a find packages/ -name manifest.yml lookup is needed.

Acceptance criteria

  • .backports.yml exists at the repo root covering all current backport branches
  • Known maintained_until dates are filled in
  • backport_check_active.sh correctly returns active/inactive per the defined logic
  • --json output is parseable and matches the schema above
  • Set for now elastic/ecosystem as a codeowner of .backports.yml file
  • Add a new step in the Buildkite main pipeline to ensure that each entry has the expected fields (package, base_version, base_commit, branch, maintained_until and archived)
  • Updating this file should trigger the CI pipeline but it should not trigger testing all packages (it should be included in the non_package_patterns list in .buildkite/scripts/common.sh)
  • Assess whether or not to run the buildkite pipeline integrations-backport in dry-run mode if .backports.yml is updated.

Activity

  1. mrodm
    marked this as blocking 2 issues on May 26, 2026

  2. github-actions commented on May 26, 2026

    @github-actions
    github-actionsBot
    on May 26, 2026 – with GitHub Actions
    Contributor

    This issue is the right next implementation slice (not a duplicate): branch creation exists, but an inventory source-of-truth and active-branch evaluator are still missing and should be added first.

    Recommendation

    Proceed with #19210 as the foundation for backport automation, with this order:

    1. Add root .backports.yml + one-time bootstrap generator.
    2. Add dev/scripts/backport_check_active.sh (--branch, --json, exit 0/1 per active logic).
    3. Wire the checker into existing backport flows and document usage.
    Findings
    • Existing backport branch creation is present and UI-driven:
      • .buildkite/pipeline.backport.yml:20-54
      • .buildkite/scripts/backport_branch.sh:79-87, .buildkite/scripts/backport_branch.sh:292-297
    • Existing workflow/docs are still manual for old-version fixes:
      • docs/extend/developer-workflow-support-old-package.md:10-16
      • docs/extend/developer-workflow-support-old-package.md:81-121
    • Nested package directory handling already exists and can be reused for inventory integrity:
      • .buildkite/scripts/backport_branch.sh:90-106 (get_package_path)
      • .buildkite/scripts/common.sh:914-916 (list_all_directories via mage)
      • magefile.go:221-231 and dev/citools/packages.go:19-50
    • Related history supports this issue’s scope:
      • #19016 (open) defines branch inventory as an unresolved gap.
      • #17403 (closed/completed) and #18577 (merged) addressed nested package-dir compatibility, not inventory/active-state policy.
      • #19104 (merged) added dev/scripts/get_release_commit.sh and docs updates, but not .backports.yml / active-check script.
    Verification

    Current repo/remote state from commands in workspace:

    $ ls -l .backports.yml dev/scripts/backport_check_active.sh
ls: cannot access '.backports.yml': No such file or directory
ls: cannot access 'dev/scripts/backport_check_active.sh': No such file or directory

$ git ls-remote --heads origin 'backport-*' | head -n 5
ed21ff84b14f166f75524f5196c933cc4069b99a	refs/heads/backport-apm-8.15
275902537f94d8347bf4c4faf3cea0a5da88a4f5	refs/heads/backport-aws-1.51
4e8c8f5f466e9115162c1f74c057647ab965d79f	refs/heads/backport-aws-2.24
8a88b2c60a29542a9943c525948cd0045d2e7435	refs/heads/backport-aws-2.25
383ea812539d5242a60f8b9ed06762588c348aea	refs/heads/backport-aws-2.30

    This confirms there are existing backport-* branches to inventory, while the requested inventory/checker artifacts are not yet present.

    Detailed Action Plan

    1. Create inventory file at repo root

      • Add .backports.yml with schema from this issue (package, branch, base_version, base_commit, maintained_until, archived).
      • Seed initial entries from existing backport-* remote branches.

    2. Add one-time bootstrap script

      • New script under dev/scripts/ to:
        • enumerate branches with git ls-remote --heads origin 'backport-*'
        • derive package/series from branch names
        • compute last-commit age and default archived: true for >1 year stale branches
        • emit/update .backports.yml
      • Then do a manual review pass to fill known maintained_until dates.

    3. Add active-status checker

      • New dev/scripts/backport_check_active.sh:
        • input: --branch <name>
        • output: human-readable by default; JSON with --json
        • exit 0 if active, 1 if inactive
        • logic: inactive when archived: true OR (maintained_until set and < today)

    4. Integrate checker where branch decisions happen

      • Start with backport branch scripts/pipelines:
        • .buildkite/scripts/backport_branch.sh
        • .buildkite/pipeline.backport.yml
      • Ensure automation never targets inactive inventory entries.

    5. Documentation updates

      • Extend docs/extend/developer-workflow-support-old-package.md with:
        • inventory semantics
        • checker usage examples (--json included)
        • expected workflow when entries are archived/expired.
    Related Items
    Type Link Relevance
    Issue #19210 Current scoped request (inventory + active-check foundation)
    Issue #19016 Parent backport tooling effort; inventory identified as unresolved gap
    Issue #17403 Completed nested directory support groundwork
    PR #18577 Merged CI/backport script updates for nested paths
    PR #19104 Merged helper script (get_release_commit.sh) + docs improvements
    File .buildkite/scripts/backport_branch.sh:79-87 Current existence check (no active/inactive policy)
    File .buildkite/scripts/backport_branch.sh:90-106 Existing package-name→path resolver to reuse
    File .buildkite/pipeline.backport.yml:20-54 Current backport pipeline entrypoint
    File docs/extend/developer-workflow-support-old-package.md:10-16 Manual workflow overview today

    Note

    🔒 Integrity filter blocked 3 items

    The following items were blocked because they don't meet the GitHub integrity level.

    • #19171 pull_request_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
    • [CI] Add Buildkite step to validate changelog PR links #19171 pull_request_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
    • #11984 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".

    To allow these resources, lower min-integrity in your GitHub frontmatter:

    tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

    What is this? | From workflow: Issue Triage

    Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

  3. mrodm
    added a parent issue on May 26, 2026
  4. mrodm
    added
    Team:EcosystemPackages Ecosystem team [elastic/ecosystem]
    on May 26, 2026

  5. infra-vault-gh-plugin-prod commented on May 26, 2026

    @infra-vault-gh-plugin-prod
    infra-vault-gh-plugin-prodBot
    on May 26, 2026

    Pinging @elastic/ecosystem (Team:Ecosystem)

  6. mrodm
    marked this as blocking 2 issues on May 28, 2026
  7. mrodm
    self-assigned this
    on May 28, 2026
  8. mrodm
    added a commit that references this issue on Jun 17, 2026

    [backports] Add .backports.yml inventory, validator, and dry-run trig…

    3cb7319
  9. mrodm
    closed this as completedin #19362on Jun 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Team:EcosystemPackages Ecosystem team [elastic/ecosystem]

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions