Improve local tooling ergonomics

[swiatekm]

This is a meta issue for improvements to the usability of our local tooling. I'd like it to cover anything achievable using mage, make and the local CI scripts. Including, but not limited to:

• Packaging
• Unit Test
• Integration tests
• Linting
• Reproducing CI failures locally in general

For reference, the kind of problem this issue is meant to include, is the fact that if I want to build a single agent package for testing locally, I need to run:

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

Why not just mage package? There's an even more annoying problem with integration tests. I'll file a dedicated sub-issue to deal with this.

[infra-vault-gh-plugin-prod]

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

[github-actions]

tl;dr: the biggest ergonomics gap is that mage package hard-fails unless PACKAGES is set, while nearby knobs (like PLATFORMS) already have defaults—so local packaging starts with an avoidable “long incantation” experience.

Recommendation

I recommend we keep the current strict behavior for CI/release-oriented paths, but add a local-friendly packaging entrypoint and improve discoverability in Mage help/docs:

1. Add a convenience target (for example package:local) that sets sensible local defaults (SNAPSHOT=true, host PLATFORMS, and a minimal default package set such as tar.gz).
2. Keep mage package strict/explicit for deterministic automation.
3. Update Package target help text to explicitly mention PACKAGES requirement and point to the convenience target.

This gives us better day-1 UX without changing existing CI semantics.

Findings

1. mage package currently requires PACKAGES and fails early when missing:

   • magefile.go:619-621
   • magefile.go:1507-1509 (PackageUsingDRA has same behavior)

2. Platform selection has a default, but package selection does not:

   • dev-tools/mage/settings.go:1861-1871 (PLATFORMS defaults to BuildPlatforms.Defaults())
   • dev-tools/mage/settings.go:1885-1897 (PACKAGES empty => GetPackageTypes() returns nil)

3. Discoverability is weak in mage target docs:

   • magefile.go:610-614 package target doc comment mentions SNAPSHOT and PLATFORMS, but not that PACKAGES is mandatory.

4. This pain has prior history:

   • Issue #6584 (“Elastic Agent cannot be packaged without PACKAGES env var”) reports the same ergonomics problem.

Verification

I attempted to validate behavior by executing Mage locally, but this runner cannot execute Mage targets due missing Mage binary / Go toolchain mismatch:

$ mage -h package
bash: mage: command not found

$ go run github.com/magefile/mage package
go: go.mod requires go >= 1.26.3 (running go 1.25.10; GOTOOLCHAIN=local)

Given that limitation, conclusions above are based on direct source inspection with file/line evidence.

Detailed Action Plan

1. Add a local packaging convenience target in magefile.go near Package (around magefile.go:610+).

   • Example behavior: derive host platform (runtime.GOOS/runtime.GOARCH), set PACKAGES=tar.gz (or configurable minimal set), set SNAPSHOT=true by default.

2. Keep Package strict as-is for automation safety.

   • Preserve current explicit guard at magefile.go:619-621 and magefile.go:1507-1509.

3. Improve help text discoverability in package target doc comments.

   • Update magefile.go:610-614 to explicitly document PACKAGES requirement and call out the convenience target.

4. Add tests for default/local behavior in settings/mage tests.

   • Extend dev-tools/mage/settings_test.go around package parsing behavior (current empty-PACKAGES semantics are asserted around referenced tests in that area).

5. Update docs/examples:

   • README.md packaging examples (README.md:108-109)
   • docs/test-framework-dev-guide.md packaging section (docs/test-framework-dev-guide.md:76-101)
   • Include both “quick local” and “fully explicit/CI-like” command forms.

Related Items

Type	Link	Relevance
Issue	#14745	This meta issue
Issue	#6584	Same core packaging ergonomics complaint (PACKAGES required)
PR	#12128	Refactored mage config handling; relevant baseline for config UX work
PR	#13234	Recent local-vs-CI ergonomics improvement in linting (useful precedent)
File	magefile.go:610-621	Package behavior and current hard failure on missing PACKAGES
File	dev-tools/mage/settings.go:1861-1900	Default behavior mismatch (PLATFORMS defaulted, PACKAGES not)
File	README.md:108-109	Current documented verbose packaging invocation
File	docs/test-framework-dev-guide.md:76-101	Integration docs requiring explicit packaging flags

Note

🔒 Integrity filter blocked 32 items

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

• #12834 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #12835 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #12836 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #13258 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #13257 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #13256 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".
• #14233 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14232 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14231 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14197 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".
• #14588 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14144 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• ... and 16 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.