_dev folder not allowed for OTel content packs in package spec

[strawgate]

For #16969 we want to start committing yaml dashboards to be repo but the dev folder is not allowed in content packs and so our buildkite build fails the main package build

We can obviously change the package spec to allow this but I don't want to require a new package version.

Can you look at the build and figure out if there is something we can do to unblock this? Maybe we can make a change to validation to ignore the folder without having to bump package versions?

Maybe we can make a _yaml folder under dashboards that we unconditionally delete prior to running the build?

[github-actions]

Claude finished @strawgate's task in 3m 42s —— View job

---

Recommendation

Add _dev folder support to the content package spec in elastic/package-spec, then update the content packages to use a compatible format_version. This is the cleanest solution and aligns with how integration packages already handle development resources.

The suggested workaround of using a _yaml folder under kibana/dashboard/ will not work because the content package kibana spec has additionalContents: false, which rejects any unspecified items.

Findings

Root Cause

The content package spec (spec/content/spec.yml in package-spec) has additionalContents: false and does not include a _dev folder definition:

Content Package Allowed Contents:

• manifest.yml (required)
• changelog.yml (required)
• docs/ (required)
• LICENSE.txt (optional)
• img/ (optional)
• kibana/ (optional)
• elasticsearch/ (optional)
• validation.yml (optional)

In contrast, the integration package spec (spec/integration/spec.yml) explicitly includes:

- description: Folder containing development resources
  type: folder
  name: _dev
  required: false
  visibility: private
  $ref: "./_dev/spec.yml"

When elastic-package build runs, it:

1. Copies the package WITHOUT _dev folders (via CopyWithoutDev() in internal/files/copy.go)
2. Validates the package against the spec

However, validation happens before the build copy, so if you have a _dev folder in a content package, the validation step fails with:

item [_dev] is not allowed in folder [packages/<package_name>]

The _yaml Subfolder Workaround Won't Work

Even if you created kibana/dashboard/_yaml/, the kibana folder spec also has additionalContents: false. Only specific patterns like {PACKAGE_NAME}-.+.json are allowed in dashboard folders. A _yaml subfolder would trigger the same "item not allowed" error.

Validation Flow

From package-spec/code/go/internal/validator/folder_spec.go:105-108:

if itemSpec == nil && !v.spec.AdditionalContents() {
    errs = append(errs,
        specerrors.NewStructuredErrorf("item [%s] is not allowed in folder [%s]", fileName, v.pkg.Path(v.folderPath)),
    )
}

Detailed Action Plan

Option 1: Update Package Spec (Recommended)

1. Open PR in elastic/package-spec to add _dev folder support to content packages:

   • Edit spec/content/spec.yml to add:

     - description: Folder containing development resources
       type: folder
       name: _dev
       required: false
       visibility: private
       $ref: "./_dev/spec.yml"

   • Create spec/content/_dev/spec.yml (can reference integration's _dev spec or create a minimal version)
   • Bump the spec version

2. After spec release, update content packages:

   • Bump format_version in manifest.yml to the new spec version
   • This requires a package version bump too

Timeline consideration: This requires coordination between package-spec and integrations repos and a spec release cycle.

Option 2: Pre-build Script (Workaround)

Add a CI step that removes YAML dashboard files before running elastic-package check/build:

1. Store YAML dashboards in a separate location tracked by git (e.g., dev/yaml-dashboards/<package>/)
2. Add a pre-build script that:
   • Converts YAML → JSON dashboards
   • Places JSON files in packages/<pkg>/kibana/dashboard/
3. Never commit _dev folders to content packages

This keeps source YAML files in version control without violating the spec.

Option 3: Store YAML Outside Package Directory

For PR #16969 specifically:

1. Store YAML dashboard definitions in dev/dashboards/aws_vpcflow_otel/ (outside packages/)
2. Create a conversion workflow that outputs to the package's kibana/dashboard/ folder
3. Commit only the generated JSON files to the package

Related Items

Repository	Issue or PR	Relevance
elastic/integrations	#16969	The PR attempting to add YAML dashboards that triggered this issue

Related Files

Repository	File	Relevance
elastic/package-spec	spec/content/spec.yml	Content package spec - missing _dev folder definition
elastic/package-spec	spec/integration/spec.yml	Integration package spec - has _dev folder support
elastic/package-spec	code/go/internal/validator/folder_spec.go	Validation logic that rejects unknown folders
elastic/elastic-package	internal/files/copy.go	Build logic that skips _dev folders during package build
elastic/integrations	packages/aws_vpcflow_otel/manifest.yml	Content package that needs YAML dashboards

---

Why is Claude responding? | Type @claude to interact further

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

[strawgate]

@claude the workaround would be to delete the yaml folder prior to the build running so it's not actually in the spec as we compile them to json and put both in the repository

[github-actions]

Claude finished @strawgate's task in 3m 27s —— View job • claude/issue-17211-20260203-1726 • Create PR ➔

---

Implemented YAML Folder Deletion Workaround

• Understand the proposed workaround
• Find where the build/validation runs in CI
• Identify how to add the deletion step
• Add helper function to remove _dev folder for content packages
• Integrate into check_package and build_zip_package
• Test and commit changes

---

Summary

I've implemented the workaround by adding a remove_dev_folder_for_content_packages() function to .buildkite/scripts/common.sh. This function:

1. Checks if the package is a content package (type: content in manifest.yml)
2. If a _dev folder exists, removes it before validation/build runs

The function is called in both check_package() and build_zip_package(), which covers:

• PR validation (via elastic-package check)
• Package publishing (via elastic-package build --zip)

Key details:

• Only affects content packages - integration packages keep their _dev folders
• The YAML source files remain in git for version control
• The compiled JSON files are what get validated/published

--- | Branch: claude/issue-17211-20260203-1726

---

Why is Claude responding? | Type @claude to interact further

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