Add changelog bundle option for --files

docs/cli-schema.json

@@ -3030,7 +3030,7 @@
           ],
           "name": "bundle",
           "summary": "Aggregate changelog entries matching a filter into a single bundle YAML.",
-          "notes": "Profile-based commands (bundle \u003Cprofile\u003E \u003Cversion|report\u003E [report] [--plan]): filters, paths, repo metadata,\nresolve, description, hide-features, and release-date behaviour come from changelog.yml. Only --plan is supported\nalongside profile positional arguments; other flags documented below as unsupported in profile-based commands must be set in\nconfiguration instead. Config is auto-discovered from ./changelog.yml or ./docs/changelog.yml. Use\nbundle.release_dates or bundle.profiles.\u003Cname\u003E.release_dates to control auto-population;\n--release-date and --no-release-date require option-based mode.\n\nOption-based mode (no profile argument): exactly one filter must be specified \u2014\n--all, --input-products, --prs, --issues, --release-version, or --report.",
+          "notes": "Profile-based commands (bundle \u003Cprofile\u003E \u003Cversion|report\u003E [report] [--plan]): filters, paths, repo metadata,\nresolve, description, hide-features, and release-date behaviour come from changelog.yml. Only --plan is supported\nalongside profile positional arguments; other flags documented below as unsupported in profile-based commands must be set in\nconfiguration instead. Config is auto-discovered from ./changelog.yml or ./docs/changelog.yml. Use\nbundle.release_dates or bundle.profiles.\u003Cname\u003E.release_dates to control auto-population;\n--release-date and --no-release-date require option-based mode.\n\nOption-based mode (no profile argument): exactly one filter must be specified \u2014\n--all, --input-products, --prs, --issues, --release-version, --report, or --files.",
           "usage": "docs-builder changelog bundle [\u003Cprofile\u003E] [\u003Cprofile-arg\u003E] [\u003Cprofile-report\u003E] [options]",
           "examples": [],
           "parameters": [
@@ -3053,7 +3053,7 @@
               "name": "profile-report",
               "type": "string",
               "required": false,
-              "summary": "Promotion report or URL list file when also providing a version. When provided, the second argument must be a version string and this is the PR/issue filter source (for example, \u0022bundle serverless-release 2026-02 ./report.html\u0022). Optional third positional argument in profile-based commands."
+              "summary": "Promotion report, URL list file, or changelog path list file when also providing a version. When provided, the second argument must be a version string and this is the filter source (for example, \u0022bundle serverless-release 2026-02 ./report.html\u0022). Optional third positional argument in profile-based commands."
             },
             {
               "role": "flag",
@@ -3158,6 +3158,23 @@
               "repeatable": true,
               "elementType": "string"
             },
+            {
+              "role": "flag",
+              "name": "files",
+              "type": "array",
+              "required": false,
+              "summary": "Filter by changelog YAML paths (comma-separated), or a path to a newline-delimited file containing changelog paths. Can be specified multiple times. Forces local entry sourcing. This option is not supported in profile-based commands; pass a path list file as the second or third positional argument instead.",
+              "repeatable": true,
+              "elementType": "string"
+            },
+            {
+              "role": "flag",
+              "name": "force-local",
+              "type": "boolean",
+              "required": false,
+              "summary": "Force local entry sourcing for this run (equivalent to bundle.use_local_changelogs: true without editing config). Allowed in profile-based commands.",
+              "defaultValue": "false"
+            },
             {
               "role": "flag",
               "name": "owner",
@@ -4007,14 +4024,14 @@
               "name": "profile-report",
               "type": "string",
               "required": false,
-              "summary": "Optional: Promotion report or URL list file when also providing a version. When provided, the second argument must be a version string and this is the PR/issue filter source."
+              "summary": "Optional: Promotion report, URL list file, or changelog path list file when also providing a version. When provided, the second argument must be a version string and this is the filter source."
             },
             {
               "role": "flag",
               "name": "all",
               "type": "boolean",
               "required": false,
-              "summary": "Remove all changelogs in the directory. Exactly one filter option must be specified: --all, --products, --prs, --issues, or --report.",
+              "summary": "Remove all changelogs in the directory. Exactly one filter option must be specified: --all, --products, --prs, --issues, --report, or --files.",
               "defaultValue": "false"
             },
             {
@@ -4088,6 +4105,15 @@
               "repeatable": true,
               "elementType": "string"
             },
+            {
+              "role": "flag",
+              "name": "files",
+              "type": "array",
+              "required": false,
+              "summary": "Filter by changelog YAML paths (comma-separated), or a path to a newline-delimited file containing changelog paths. Can be specified multiple times. Not supported in profile-based commands; pass a path list file as a positional argument instead.",
+              "repeatable": true,
+              "elementType": "string"
+            },
             {
               "role": "flag",
               "name": "owner",
@@ -4130,7 +4156,7 @@
               "name": "report",
               "type": "string",
               "required": false,
-              "summary": "Optional (option-based mode only): URL or file path to a promotion report. Extracts PR URLs and uses them as the filter. Mutually exclusive with --all, --products, --prs, --release-version, and --issues."
+              "summary": "Optional (option-based mode only): URL or file path to a promotion report. Extracts PR URLs and uses them as the filter. Mutually exclusive with --all, --products, --prs, --release-version, --issues, and --files."
             },
             {
               "role": "flag",

docs/cli/changelog/cmd-bundle.md

@@ -17,9 +17,10 @@ docs-builder changelog bundle elasticsearch-release 9.2.0 ./promotion-report.htm
 The second positional argument accepts:
 - A version string (e.g. `9.2.0`, `9.2.0-beta.1`) — lifecycle is inferred automatically (`ga`, `beta`, `rc`)
 - A promotion report URL or file path
-- A plain-text URL list file (one fully-qualified GitHub URL per line)
+- A plain-text URL list file (one fully-qualified GitHub PR or issue URL per line)
+- A plain-text path list file (one changelog YAML path per line, ending in `.yaml` or `.yml`)
 
-When your profile uses `{version}` in its output pattern and you also want to filter by a report, pass both arguments.
+When your profile uses `{version}` in its output pattern and you also want to filter by a report or list file, pass both arguments (version first, then the filter file).
 
 Example profile in `changelog.yml`:
 
@@ -48,6 +49,9 @@ Exactly one of the following filter flags is required:
 - `--issues` — filter by issue URLs or a newline-delimited file of issue URLs
 - `--release-version` — fetch PR references from a GitHub release tag (e.g. `v9.2.0` or `latest`)
 - `--report` — filter by PRs referenced in a promotion report (URL or local file)
+- `--files` — include specific changelog YAML paths, or a newline-delimited path list file
+
+`--force-local` is not a filter. It forces local entry sourcing for the run (equivalent to `bundle.use_local_changelogs: true` without editing config) and is allowed in both option-based and profile-based modes.
 
 ```sh
 # Bundle all changelogs in docs/changelog/
@@ -63,6 +67,12 @@ docs-builder changelog bundle \
   --release-version v9.2.0 \
   --repo elasticsearch \
   --owner elastic
+
+# Bundle an explicit list of changelog files
+docs-builder changelog bundle \
+  --files "./docs/changelog/a.yaml,./docs/changelog/b.yaml" \
+  --output docs/releases/serverless/2026-07-07.yaml \
+  --output-products "cloud-serverless 2026-07-07"
 ```
 
 ## Resolved vs. reference bundles
@@ -317,6 +327,43 @@ docs-builder changelog bundle \
 By default all changelogs that match PRs in the promotion report are included in the bundle.
 To apply additional filtering by the changelog type, areas, or products, add [rules.bundle](/contribute/configure-changelogs-ref.md#rules-bundle) configuration settings.
 
+### Bundle by file paths [changelog-bundle-files]
+
+Use `--files` when you know the exact changelog files to include and they may not have `prs` or `issues` metadata.
+
+```sh
+docs-builder changelog bundle \
+  --files "./docs/changelog/a.yaml,./docs/changelog/b.yaml" \
+  --output docs/releases/serverless/2026-07-07.yaml \
+  --output-products "cloud-serverless 2026-07-07"
+```
+
+You can also pass a newline-delimited path list file:
+
+```sh
+docs-builder changelog bundle --files ./docs/temp/changelog_files.txt --output ...
+```
+
+In profile mode, pass the same path list as a positional argument:
+
+```sh
+docs-builder changelog bundle serverless-release 2026-07-07 ./docs/temp/changelog_files.txt
+```
+
+`--files` / path-list selection always reads the named files from disk (local entry sourcing). It does not fetch entries from the CDN. `rules.bundle` still applies after selection.
+
+### Force local entry sourcing [changelog-bundle-force-local]
+
+When a repository defaults to CDN entry sourcing, you can use `--force-local` to read changelog YAML files from the local folder.
+This option overrides the `bundle.use_local_changelogs` setting in your `changelog.yml` and is useful for ad hoc bundles that include freshly authored local files that are not on the CDN yet.
+
+```sh
+docs-builder changelog bundle serverless-release 2026-07-07 ./docs/temp/prs.txt --force-local
+```
+
+`--force-local` is allowed in both option-based and profile-based commands.
+Path-list / `--files` filters already force local sourcing, so `--force-local` is optional in that case.
+
 ### Hide features [changelog-bundle-hide-features]
 
 You can use the `--hide-features` option to embed feature IDs that should be hidden when the bundle is rendered. This is useful for features that are not yet ready for public documentation.

docs/cli/changelog/cmd-remove.md

@@ -5,7 +5,7 @@ Remove changelog YAML files from a directory.
 Two mutually exclusive modes are available:
 
 - **Profile-based**: `docs-builder changelog remove <profile> <version|promotion-report>` — uses the same `bundle.profiles` configuration as [`changelog bundle`](/cli/changelog/bundle.md) to determine which changelogs to remove.
-- **Option-based**: `docs-builder changelog remove --products "..."` (or `--prs`, `--issues`, `--all`, `--release-version`, `--report`) — specify the filter directly.
+- **Option-based**: `docs-builder changelog remove --products "..."` (or `--prs`, `--issues`, `--all`, `--release-version`, `--report`, `--files`) — specify the filter directly.
 
 Before deleting anything, the command checks whether any matching files are referenced by unresolved bundles, to prevent silently breaking the `{changelog}` directive.
 
@@ -46,7 +46,7 @@ Setting `bundle.directory` and `bundle.output_directory` in `changelog.yml` is r
 
 ## Option-based examples
 
-Exactly one filter must be specified: `--all`, `--products`, `--prs`, `--issues`, `--release-version`, or `--report`.
+Exactly one filter must be specified: `--all`, `--products`, `--prs`, `--issues`, `--release-version`, `--report`, or `--files`.
 
 ```sh
 # Preview what would be removed (dry run)
@@ -59,6 +59,9 @@ docs-builder changelog remove \
 
 # Preview using the latest release
 docs-builder changelog remove --release-version latest --dry-run
+
+# Remove an explicit list of changelog files
+docs-builder changelog remove --files "./docs/changelog/a.yaml,./docs/changelog/b.yaml" --dry-run
 ```
 
 :::{note}

docs/contribute/bundle-changelogs.md

@@ -24,8 +24,10 @@ The source of truth can be:
 - automated release notes for GitHub releases
 - all changelog files that exist in a specific folder
 - all changelog files that match specific products, versions, and lifecycles
+- an explicit list of changelog file paths
 
 Deriving the source of truth from the contents of a folder or from the metadata in changelogs are the least accurate options (unless you have additional processes to confirm the validity of that information).
+An explicit path list is appropriate for ad hoc releases where a small set of known changelog files must be bundled and those entries may not have `prs` or `issues` fields.
 It is recommended to use lists that are generated as part of your release coordination activities.
 Consider your options carefully and discuss with your docs team if necessary.
 
@@ -54,13 +56,14 @@ It is strongly recommended to set `output_products` in your profile so your bund
 
 For the most up-to-date changelog configuration options, refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) and [](/contribute/configure-changelogs-ref.md).
 
-### Bundle by report or URL list [profile-url]
+### Bundle by report, URL list, or path list [profile-url]
 
 If the source of truth for what was shipped in each release is:
 
 - a list of GitHub pull requests
 - a list of GitHub issues
 - a buildkite promotion report (which contains a list of PRs)
+- an explicit list of changelog YAML paths (one `.yaml`/`.yml` path per line)
 
 ... your profile does not have any mandatory settings.
 However it's a good idea to define the [basic bundle settings](/contribute/configure-changelogs-ref.md#bundle-basic) and the [profile settings](/contribute/configure-changelogs-ref.md#bundle-profiles) for the output filename and output products.
@@ -164,11 +167,12 @@ The `products` field determines which changelog files are gathered for considera
 If you created profiles, you can use them with the `changelog bundle` command like this:
 
 ```sh
-docs-builder changelog bundle <profile> <version|report|url-list>
+docs-builder changelog bundle <profile> <version|report|url-list|path-list>
 ```
 
-The second argument accepts a version string, a promotion report URL or path, or a URL list file (a plain-text file with one fully-qualified GitHub URL per line).
-If you are using a `{version}` placeholder in the `output_products` or `output` fields, you must provide that value as well as your report or URL argument.
+The second argument accepts a version string, a promotion report URL or path, a URL list file (a plain-text file with one fully-qualified GitHub URL per line), or path list file (one changelog file path per line).
+
+If you are using a `{version}` placeholder in the `output_products` or `output` fields, you must provide that value as well as your report or list argument.
 
 For example, if the source of truth for what was shipped in each release is:
 
@@ -193,6 +197,20 @@ For example, if the source of truth for what was shipped in each release is:
   docs-builder changelog bundle serverless-report 2026-02-13 ./promotion-report.html
   ```
 
+- a list of changelog files:
+
+  ```sh
+  # Bundle changelogs from a file list ({version} → "2026-07-17")
+  docs-builder changelog bundle serverless-release 2026-07-17 ./changelogs.txt
+  ```
+
+  ... where `changelogs.txt` is a newline delimited file with paths like this this:
+
+  ```txt
+  docs/changelog/1770424335-adhoc-security-fix.yaml
+  docs/changelog/1770424401-adhoc-feature.yaml
+  ```
+
 - automated release notes for GitHub releases:
 
   ```sh
@@ -231,7 +249,7 @@ For example, if the source of truth for what was shipped in each release is:
 By default all changelogs that match the chosen source of truth are included in the bundle.
 
 :::{tip}
-It is strongly recommended to pull all of the content from each changelog into the bundle; otherwise you can't move or remove your changelogs. If your bundle contains only references to the files, add set [bundle.resolve](/contribute/configure-changelogs-ref.md#bundle-basic) to true and re-generate your bundle.
+It is strongly recommended to pull all of the content from each changelog into the bundle; otherwise you can't move or remove your changelogs. If your bundle contains only references to the files, set [bundle.resolve](/contribute/configure-changelogs-ref.md#bundle-basic) to true and re-generate your bundle.
 :::
 
 To apply additional filtering by the changelog type, areas, or products, add [bundle rules](#rules).
@@ -285,7 +303,7 @@ You can use the `docs-builder changelog remove` command to remove changelogs.
 If you created profiles, you can use them like this:
 
 ```sh
-docs-builder changelog remove <profile> <version|report|url-list>
+docs-builder changelog remove <profile> <version|report|url-list|path-list>
 ```
 
 For example, if the source of truth for what was shipped in each release is:
@@ -302,6 +320,12 @@ For example, if the source of truth for what was shipped in each release is:
   docs-builder changelog remove serverless-report ./promotion-report.html
   ```
 
+- a list of changelog files:
+
+  ```sh
+  docs-builder changelog remove serverless-release ./changelogs.txt
+  ```
+
 - automated release notes for GitHub releases:
 
   ```sh

docs/contribute/configure-changelogs-ref.md

@@ -73,9 +73,11 @@ The authoring repo is resolved with the same precedence as `changelog upload`: `
 
 Sourcing is decided per run:
 
-- **Local folder.** Used when `bundle.use_local_changelogs: true`, when `--directory` is passed, or when the authoring repo cannot be resolved. The folder must contain the changelog files.
+- **Local folder.** Used when `bundle.use_local_changelogs: true`, when `--force-local` is passed, when `--files` / a path-list filter is used, when `--directory` is passed, or when the authoring repo cannot be resolved. The folder must contain the changelog files.
 - **CDN (default when a repo resolves).** Used when the authoring repo resolves, local sourcing is not forced, and a CDN base URL is configured (`DOCS_BUILDER_CHANGELOG_CDN`, defaulting to the public distribution). The command fetches `changelog/{org}/{repo}/{branch}/registry.json` and the entries it lists, then applies the bundle's own product/PR/issue filters to the downloaded set.
 
+Use `--force-local` for uncommon ad hoc runs that need the local folder without editing `changelog.yml`. Path-list / `--files` filters always force local sourcing because they select files by path on disk.
+
 Because entries are org/repo/branch-scoped, one repository can produce a bundle for a shared product (for example, `cloud-serverless`) while sourcing its own entries from `changelog/{org}/{repo}/{branch}/`, without that product appearing in the repository's `docset.yml`. The `{changelog}` directive's `:cdn:` mode still consumes product-scoped *bundles*, so a repository that also renders its own release notes declares each product under `release_notes` as before.
 
 ### Bundle descriptions [bundle-descriptions]