---
name: n8n:env-var-docs
description: >-
  Writes and reviews the JSDoc on `@Env(...)` config properties. The docs team extracts these comments from source into the public environment variable reference, so they are user documentation, not code comments. Use when adding or changing an `@Env` property, a config class, or reviewing a PR that touches one.
title: n8n:env-var-docs
canonical_url: https://skilld.dev/gh/n8n-io/n8n/env-var-docs
last_updated: 2026-10-15T10:16:00.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install n8n-io/n8n/env-var-docs`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/env-var-docs`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/n8n-io/n8n/env-var-docs) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/env-var-docs`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/env-var-docs --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/env-var-docs --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Environment variable docs

The JSDoc above every `@Env('...')` property is exported almost verbatim into
the [environment variables reference](https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/use-environment-variables)
on docs.n8n.io. The generated table has four columns: variable name,
description, data type, default. Your JSDoc is the description column. The
reader is a self-hosting operator, not an n8n developer.

Follow the [n8n docs style guide](https://docs.n8n.io/contribute/contribution-guide-for-n8n-docs/style-guide-for-n8n-docs)
for these comments. It overrides the ASD-STE100 rule in `AGENTS.md` for this
one case. The rules below are the parts of that guide that matter for a
one-paragraph description.

## Rules

- **Every `@Env` property has a JSDoc.** No exceptions. A missing comment
  ships as an empty description cell.
- **Write for the operator.** Say what the setting does, when to change it,
  and what happens when it's unset or wrong. Don't explain why the code is
  written the way it is.
- **No code references.** No file names, class names, function names,
  constants, license keys, or other internals the reader can't open. Values
  the operator types into the variable are fine and often needed, for example
  a credential type ID like `googleOAuth2Api` or a mode like `postgresdb`.
  The test: would the operator paste this into a config file, or would they
  need the source to know what it means? Details for developers go in a
  regular `//` comment on the implementation, not in the JSDoc.
- **No attack scenarios.** Say what the setting protects, not how an
  attacker would exploit it. This is a public page.
- **Don't repeat the default.** The default renders in its own column. Don't
  write "Defaults to true" or "Default: 1 hour". Do say what the unset state
  means when it's not obvious, for example "When unset, n8n uses the Redis
  host".
- **State units and formats.** Say "in milliseconds", "in bytes", "a
  comma-separated list", "a JSON object". The data type column only says
  `Number` or `String`.
- **Use allowed values when the set is small.** "One of `sqlite`,
  `postgresdb`." For a list, show one inline example in the sentence.
- **No JSDoc tags.** No `@example`, `@default`, `@see`, `@deprecated`. The
  exporter copies the tag name into the docs. Put the example or the
  deprecation notice in a sentence instead.
- **Product names:** "Gateway credits", not "n8n Connect" or "AI Gateway".
  "Publish a workflow", not "activate". `n8n` is always lowercase.
- **Style:** present tense, active voice, second person. Use contractions.
  No em dashes, use a comma or a new sentence. No "e.g." or "i.e.", write
  "for example" and "that is". Spell out zero to nine, numerals from 10.
  Values the operator types stay numerals, for example "Set to 0".
  Sentence case. One idea per sentence. End every sentence with a period.
- **Plain words:** "use" not "utilize", "lets you" not "allows you to", cut
  "powerful", "seamless", "simply", "it's important to note".
- **Length:** one to three sentences. If the setting needs more, the extra
  belongs in a docs page the comment can't link to yet; keep the comment to
  what fits a table cell.

## Examples

Bad, as found in the generated docs:

```ts
/**
 * Instance-level enablement for n8n Connect (AI Gateway). Licensed instances
 * are enabled by default; false opts out. Budget / free allowance still comes
 * from the license (`quota:aiGatewayBudget`).
 */
```

Wrong product name, a restated default, and an internal license key. Good:

```ts
/**
 * Whether Gateway credits are available on this instance. Set to false to
 * turn them off on a licensed instance. The credit allowance comes from your
 * license.
 */
```

Bad:

```ts
/**
 * Time to live in milliseconds for Redis cache entries. Set to 0 to disable
 * expiry. Default: 1 hour.
 */
```

The default is already in the table. Good:

```ts
/**
 * Time to live in milliseconds for Redis cache entries. Set to 0 to keep
 * entries until Redis evicts them.
 */
```

Bad:

```ts
/**
 * Comma-separated list of credential types for which overwrites are skipped
 * when the credential has been customized.
 * @example `N8N_SKIP_CREDENTIAL_OVERWRITE=zohoOAuth2Api,salesforceOAuth2Api`
 */
```

The `@example` tag lands in the description as literal text. Good:

```ts
/**
 * Comma-separated list of credential types to skip when applying credential
 * overwrites, for example `zohoOAuth2Api,salesforceOAuth2Api`. n8n skips an
 * overwrite only when a user has already changed one of its fields.
 */
```

Bad:

```ts
/**
 * Bind OAuth credential callbacks to the browser that initiated the flow.
 * When enabled, a session-scoped `n8n-oauth-binding` cookie is set on flow
 * initiation and verified on callback. Defeats phishing attacks where an
 * attacker injects an OAuth authorize URL into a victim's browser to land
 * tokens on the attacker's credential.
 */
```

Attack narrative and an internal cookie name on a public page. Good:

```ts
/**
 * Whether an OAuth credential connection must finish in the same browser
 * that started it. When enabled, n8n rejects the callback if it arrives
 * from a different browser.
 */
```

## Review checklist

When you review a PR that adds or changes an `@Env` property, check each
comment against this list and quote the fix in the review:

1. JSDoc present.
2. No code identifiers, file names, or internal keys.
3. No default restated.
4. Units, format, or allowed values stated.
5. No JSDoc tags.
6. No em dashes, Latin abbreviations, or filler words.
7. Reads correctly as a sentence in a table cell with no surrounding context.
