Switch to better packaging defaults

[swiatekm]

If I want to build a local package for testing, I need to run:

EXTERNAL=true SNAPSHOT=true PACKAGES=tar.gz PLATFORMS=linux/amd64 mage package

These should all be the defaults, and CI should explicitly set the values it wants instead.

For PACKAGES, the default should depend on PLATFORMS - tar.gz for unix, zip for Windows, both if both platforms are set.

[infra-vault-gh-plugin-prod]

Pinging @elastic/elastic-agent-control-plane (Team:Elastic-Agent-Control-Plane)

[github-actions]

tl;dr: The issue is valid; the clean implementation is to make PACKAGES default from selected platforms and remove the hard PACKAGES-required guard, but first pin explicit PLATFORMS/PACKAGES in the integration packaging pipeline so CI behavior does not silently change.

Recommendation

Implement platform-aware defaults in settings (tar.gz for non-Windows, zip for Windows, both for mixed platform sets), then remove the PACKAGES hard-fail checks in packaging targets. In parallel, make the integration packaging pipeline explicit about PLATFORMS/PACKAGES before changing defaults.

Findings

• magefile.go:619-621 and magefile.go:1507-1509 currently hard-fail when PACKAGES is unset.
• dev-tools/mage/settings.go:1890-1898 returns nil package types when PACKAGES is empty.
• dev-tools/mage/settings.go:1937-1941 treats empty selection as "all package types selected" for selection checks.
• dev-tools/mage/settings.go:1867-1871 uses default platform list when PLATFORMS is unset.
• dev-tools/mage/platforms.go:22,24,30,34,56,57 shows defaults include both unix and windows targets.
• dev-tools/packaging/packages.yml:877-878,890-891,904-905 maps windows package type to zip, darwin/linux to tgz.
• .buildkite/pipeline.integration-test-matrix.yml:15-17 calls .buildkite/scripts/steps/integration-package.sh with no env overrides.
• .buildkite/scripts/steps/integration-package.sh:12-17 sets SNAPSHOT/EXTERNAL but not PLATFORMS or PACKAGES, then runs mage package.
• Docs currently describe PACKAGES as required: README.md:108-109, docs/test-framework-dev-guide.md:97-99, AGENTS.md:89.
• docs/test-framework-dev-guide.md:457 already has an example without PACKAGES, so docs are inconsistent today.

Verification

I ran focused settings tests in dev-tools/mage:

go test ./dev-tools/mage -run 'TestSettingsGetPackageTypes|TestDefaultSettings|TestLoadSettings/loads build settings from env vars' -count=1

Initial run failed due local toolchain mismatch:

go: go.mod requires go >= 1.26.3 (running go 1.25.10; GOTOOLCHAIN=local)

Re-run with automatic toolchain selection:

GOTOOLCHAIN=auto go test ./dev-tools/mage -run 'TestSettingsGetPackageTypes|TestDefaultSettings|TestLoadSettings/loads build settings from env vars' -count=1

Result:

ok   github.com/elastic/elastic-agent/dev-tools/mage 0.019s

Detailed Action Plan

1. In dev-tools/mage/settings.go (GetPackageTypes, around 1890+), add fallback inference when CrossBuild.Packages == "":
   • Evaluate GetPlatforms().
   • If any Windows platform present, include Zip.
   • If any non-Windows platform present, include TarGz.
   • Return deduplicated list.
2. In magefile.go (Package and PackageUsingDRA, around 619+ and 1507+), remove/replace the explicit PACKAGES env var is required guard so inferred defaults are accepted.
3. Update pipeline safety before behavior change:
   • Add explicit PLATFORMS and PACKAGES env in .buildkite/pipeline.integration-test-matrix.yml for the integration-package.sh step.
4. Add/extend tests in dev-tools/mage/settings_test.go:
   • PLATFORMS=linux/... and unset PACKAGES => TarGz.
   • PLATFORMS=windows/... and unset PACKAGES => Zip.
   • mixed platforms and unset PACKAGES => both.
   • existing explicit PACKAGES values still override.
5. Update docs to match new defaults:
   • README.md packaging command section.
   • docs/test-framework-dev-guide.md packaging variables section.
   • AGENTS.md packaging notes.

Related Items

Type	Link	Relevance
Issue	#14745	Parent meta issue for local tooling ergonomics
Issue	#14746	This packaging-defaults subtask
File	magefile.go:614-621	Current hard requirement for PACKAGES in Package
File	magefile.go:1502-1509	Same hard requirement in PackageUsingDRA
File	dev-tools/mage/settings.go:1865-1910	Platform and package-type derivation points
File	.buildkite/pipeline.integration-test-matrix.yml:15-17	CI path currently not explicit on PLATFORMS/PACKAGES
File	.buildkite/scripts/steps/integration-package.sh:12-17	mage package invocation without PACKAGES
File	dev-tools/packaging/packages.yml:877-878,890-891,904-905	Confirms zip vs tgz mapping by OS

Note

🔒 Integrity filter blocked 18 items

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

• #13320 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #2579 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14719 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14597 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14398 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14504 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #8337 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #9048 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #7173 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #4925 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14135 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14136 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14137 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #13478 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14719 list_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14735 list_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• ... and 2 more items

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.