nodejs/node · error · Error

GitHub Actions workflow must be just a file not a path

Error message

GitHub Actions workflow must be just a file not a path

What it means

Thrown by the GitHub trust provider's `validateFile` when the `--file` value is not equal to its own basename, i.e. it contains path separators. The trust record references a single workflow file inside `.github/workflows/`, so only a bare filename is accepted — not a relative or absolute path.

Source

Thrown at deps/npm/lib/commands/trust/github.js:66

    globalDefinitions.yes,
  ]

  getEntityUrl ({ providerHostname, file, entity }) {
    if (file) {
      return new URL(`${entity}/blob/HEAD/.github/workflows/${file}`, providerHostname).toString()
    }
    return new URL(entity, providerHostname).toString()
  }

  validateEntity (entity) {
    if (entity.split('/').length !== 2) {
      throw new Error(`${this.constructor.providerEntity} must be specified in the format owner/repository`)
    }
  }

  validateFile (file) {
    if (file !== path.basename(file)) {
      throw new Error('GitHub Actions workflow must be just a file not a path')
    }
  }

  static optionsToBody (options) {
    const { file, repository, environment } = options
    const trustConfig = {
      type: 'github',
      claims: {
        repository,
        workflow_ref: {
          file,
        },
        ...(environment) && { environment },
      },
    }
    return trustConfig
  }

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Pass only the filename, e.g. `--file deploy.yml`.
2. Strip any directory: `path.basename(file)` before passing.
3. Ensure the value has no leading `./`, no subdirectory, and no path separator.

Example fix

// before
--file .github/workflows/deploy.yml
// after
--file deploy.yml

const path = require('path')
function normalizeWorkflowFile(file) {
  const base = path.basename(file)
  if (base !== file) {
    throw new Error(`--file must be a bare filename (e.g. deploy.yml), got "${file}"`)
  }
  return base
}

function isBareFilename(file) {
  return path.basename(file) === file
}

When it happens

Trigger: `file !== path.basename(file)` — the value contains a `/` (or, on Windows, a `\`) making it more than a filename.

Common situations: Passing `.github/workflows/deploy.yml`, `./deploy.yml`, or an absolute path instead of just `deploy.yml`; templating that injects a directory prefix.

Related errors

• ${this.constructor.providerEntity} must be specified in the
• vcs-origin must not include a scheme (e.g., use 'github.com/
• vcs-origin must be in format 'provider/owner/repo'
• Package name must be specified either as an argument or in p
• org-id is required

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/2462c942d58deded. Report an issue: GitHub.