env-vars skill prescribes a pattern that silently corrupts HTTP-header secret values

Open Beginner friendly
#58 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
84/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
shell
Domain
documentation

Research direction

Start in skills/env-vars/SKILL.md at the non-interactive, multi-environment, and branch-scoped examples around lines 108-112 and 234. Replace the echo-based commands with one of the suggested newline-safe patterns, add the explanation about trailing newlines and secret corruption, and verify all affected examples consistently avoid echo.

Written by the indexing model from the issue text.

Description

env-vars skill teaches the echo | vercel env add pattern, which silently corrupts HTTP-header secret values

The env-vars skill at skills/env-vars/SKILL.md (v0.40.0 verified) shows the echo "secret-value" | vercel env add ... pattern in multiple places:

  • Line 108-109 (Non-interactive example)
  • Line 111-112 (multi-env example)
  • Line 234 (branch-scoped example)

echo appends a trailing \n which Vercel stores. For any env var used as an HTTP-header value (e.g., CRON_SECRET, webhook verification secrets, Authorization: Bearer $X), Vercel's build-time validator rejects the deploy with "contains leading or trailing whitespace, which is not allowed in HTTP header values".

For other secret types (API keys compared as strings, webhook signing secrets verified via HMAC), the corruption is silent — the value is stored with the trailing newline, comparisons fail at runtime, and debugging lands on "why is my HMAC signature wrong."

Repro

echo "some-secret-value" | vercel env add MY_SECRET production
vercel deploy --prod
# → Error: The `MY_SECRET` environment variable contains leading or
#   trailing whitespace, which is not allowed in HTTP header values.

Suggested fix

Update the skill to prescribe one of:

  1. printf '%s' "$VALUE" | vercel env add NAME env — portable, no trailing newline
  2. vercel env add NAME env < /path/to/secretfile — the official pattern documented at vercel.com/docs/cli/env, also avoids bash history leak

Option 2 is safest and matches Vercel's own docs. A short callout explaining why (echo appends \n, corrupts header values, silent on non-header secrets) would keep future readers from hitting this.

Happy to open a PR if useful.

Related

  • vercel/vercel#14371 — CLI-level warn/strip request
  • anthropics/claude-code#29176 — Claude-specific repro

Hit this in production 2026-04-17 via a Claude-generated command that followed this skill verbatim.

Dominant language
TypeScript
Stars
287
Forks
58
Avg merge
1d 24m
Merged PRs (30d)
18

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from vercel/vercel-plugin

All issues in vercel/vercel-plugin

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.