Require explicit workflow paths

README.md

@@ -33,23 +33,23 @@ steps:
     key: "gha-ci"
     plugins:
       - github-actions#v0.9.3:
-          workflow: .github/workflows/ci.yml
+          workflows:
+            - .github/workflows/ci.yml
 
   - label: ":rocket: Deploy"
     depends_on: "gha-ci"
     command: .buildkite/deploy.sh
 ```
 
-The plugin is a thin wrapper around the hidden `buildkite-gha plugin` entrypoint. It uses mise to install and verify the selected CLI release, and defaults to the latest stable release. During the preview, leaving `version` unset means there is no CLI version to update as new stable releases ship.
-
-Use `workflow: "*"` to select every tracked `.yml` and `.yaml` file directly under `.github/workflows`.
+The plugin is a thin wrapper around the hidden `buildkite-gha plugin` entrypoint. It uses mise to install and verify the selected CLI release, and defaults to the latest stable release. During the preview, leaving `version` unset means there is no CLI version to update as new stable releases ship. List every workflow to import explicitly; plugin configuration does not accept directories or glob patterns.
 
 To hold the CLI at a specific release instead, set `version` to an exact stable release from `0.9.0` onward:
 
 ```yaml
 plugins:
   - github-actions#v0.9.3:
-      workflow: .github/workflows/ci.yml
+      workflows:
+        - .github/workflows/ci.yml
       version: "0.10.1"
 ```
 
@@ -60,7 +60,8 @@ labels with a native Darwin/arm64 queue:
 ```yaml
 plugins:
   - github-actions#v0.9.3:
-      workflow: .github/workflows/ci.yml
+      workflows:
+        - .github/workflows/ci.yml
       runners:
         - runs-on: ubuntu-latest
           queue: hosted
@@ -72,7 +73,7 @@ Configured Linux profiles use the matching Noble or Jammy hosted-toolchains
 image. A macOS label selects native Darwin/arm64, not a GitHub image or Xcode
 inventory.
 
-The imported workflow is a dynamic part of the Buildkite pipeline. Upload can take one tracked workflow glob or a list of explicit workflow paths and creates one aggregate group per directly runnable workflow in a single transaction. Workflows that do not declare the selected event become skipped groups. Each `:github: <workflow>` group depends on the importer; its GitHub check is named `Buildkite / <workflow> (<event>)`. This approach lets you keep existing workflows while moving jobs to native Buildkite steps over time.
+The imported workflows are a dynamic part of the Buildkite pipeline. The plugin creates one aggregate group per explicitly listed, directly runnable workflow in a single transaction. Workflows that do not declare the selected event become skipped groups. Each `:github: <workflow>` group depends on the importer; its GitHub check is named `Buildkite / <workflow> (<event>)`. This approach lets you keep existing workflows while moving jobs to native Buildkite steps over time.
 
 Buildkite owns build creation and schedule configuration. Within that build, `buildkite-gha` maps push, pull request, manual/API, and scheduled builds to `push`, `pull_request`, `workflow_dispatch`, and `schedule`, then applies the matching `on:` branch, tag, base-branch, and pull request activity filters. Cross-event workflows are excluded before event-dependent compilation and retained as skipped groups.
 

docs/cli.md

@@ -102,33 +102,26 @@ buildkite-gha upload .github/workflows/ci.yml
 The importer must run on Linux/amd64 with `BUILDKITE=true` and `BUILDKITE_STEP_KEY`.
 
 The hidden zero-argument `buildkite-gha plugin` entry point reads `workflows` and
-`runners` from `BUILDKITE_PLUGIN_CONFIGURATION`; `workflows` accepts one selector
-string or an array of explicit paths. It also accepts the plugin-owned `version`,
-`source-ref`, and `minimum-release-age` fields. The legacy singular `workflow`
-field remains supported for released plugin compatibility but cannot be combined
-with `workflows`. The Linux/amd64 importer fetches the same release's Darwin
-runtime only when a workflow requires it. Custom importers can use the public
-flags below.
+`runners` from `BUILDKITE_PLUGIN_CONFIGURATION`. Every `workflows` entry must be
+an explicit path to a regular, tracked `.yml` or `.yaml` file inside the
+repository; directories and glob patterns are rejected. It also accepts the
+plugin-owned `version`, `source-ref`, and `minimum-release-age` fields. The legacy
+singular `workflow` field remains supported as an explicit-path compatibility
+alias for released plugins but cannot be combined with `workflows`. The
+Linux/amd64 importer fetches the same release's Darwin runtime only when a
+workflow requires it. Custom importers can use the public flags below.
 
 ### Select workflows
 
-Use `*` for every tracked `.yml` and `.yaml` file directly under `.github/workflows`:
-
-```sh
-buildkite-gha upload '*'
-```
-
-Quote `*` in shells and YAML. A single operand can also be a literal file, directory, or tracked glob. Matches are canonicalized, sorted, and deduplicated before workflow identities and job-key namespaces are assigned. Existing filenames containing `*`, `?`, or `[` remain literal.
-
-Two or more operands switch to explicit-list mode:
+Pass every workflow path explicitly:
 
 ```sh
 buildkite-gha upload -- \
   .github/workflows/ci.yml \
   .github/workflows/release.yml
 ```
 
-Every list entry must resolve to one regular, tracked `.yml` or `.yaml` file inside the repository. Aliases and duplicates are canonicalized, deduplicated, and sorted, so reversed arguments produce the same pipeline. Directories, missing or untracked files, files outside the repository, other extensions, and symlinks are rejected before any workflow is parsed or Buildkite command runs. A tracked filename containing glob metacharacters remains literal, but an unmatched glob mixed into a list—or two glob operands—is rejected rather than expanded independently.
+Every operand must name one regular `.yml` or `.yaml` file. When uploading more than one workflow, every path must be tracked inside the repository. Aliases and duplicates are canonicalized, deduplicated, and sorted, so reversed arguments produce the same pipeline. Directories, globs, missing files, other extensions, and symlinks are rejected before any workflow is parsed or Buildkite command runs; aggregate uploads also reject untracked and outside paths.
 
 `--` ends option parsing and is required when a path operand begins with `-`; options must appear before it. Without `--`, a leading-dash operand is an unknown option. The CLI does not split shell strings or decode a JSON or YAML list from one argument: custom wrappers should pass each path as a separate argument and use `--` before externally supplied operands.
 

docs/compatibility.md

@@ -59,7 +59,7 @@ Steps remain inside one job because they share a workspace, environment files, a
 
 ### Aggregate workflow upload
 
-`*` selects every tracked `.yml` and `.yaml` file directly under `.github/workflows`. Upload also accepts one literal, directory, or tracked glob, or two or more explicit workflow paths. Lists require regular, tracked `.yml` or `.yaml` files inside the repository; directories, missing or untracked files, outside paths, symlinks, and globs fail. Inputs are canonicalized, sorted, and deduplicated before workflow identities and job-key namespaces are assigned.
+The plugin and public `upload` command require explicit workflow paths. Plugin entries and aggregate `upload` operands must identify regular, tracked `.yml` or `.yaml` files inside the repository; directories, missing or untracked files, outside paths, symlinks, and globs fail. A custom importer may upload one explicit regular workflow outside the repository. Inputs are canonicalized, sorted, and deduplicated before workflow identities and job-key namespaces are assigned.
 
 All directly runnable workflows are represented in one artifact and pipeline transaction. Each becomes one aggregate group labeled `:github: <workflow-name>`, with its canonical path as the fallback for an unnamed workflow. A workflow that declares the effective event compiles into child jobs. A workflow that does not declare it becomes a skipped group with an ignored placeholder and no plan artifacts. The label is static across events. The group-level GitHub check is named `Buildkite / <workflow-name-or-path> (<effective-event>)`. Each group depends on the importer, while its child jobs omit that redundant dependency and their own check notifications.