---
title: Env & Secrets
description: Use .env, .env.secrets.local, hook output, and CLI variables without leaking credentials into test files or artifacts.
---



agent-qa separates non-secret variables from secrets. Keep stable web test data in `.env`, sensitive values in `.env.secrets.local`, and temporary runtime values in hook output.

## Web variable example [#web-variable-example]

```dotenv
TASK_API_URL=http://localhost:3000/api
TASK_TITLE=Release checklist review
TASK_DESCRIPTION=Validate that a release checklist task can be created and completed.
STATUS_IN_PROGRESS=In Progress
STATUS_DONE=Done
TASK_PRIORITY=Urgent
```

```dotenv
TASK_API_KEY=restricted-ci-token
LOGIN_EMAIL=qa-user@company.test
LOGIN_PASSWORD=temporary-test-password
```

## workspace.envFile [#workspaceenvfile]

```yaml
workspace:
  envFile: .env
```

Description: Points agent-qa at a dotenv-style file for non-secret variables.

Possible values: any non-empty workspace-relative path.

Required: yes in `agent-qa.config.yaml`.

Default: none. The referenced file must exist, even if it is empty.

Use non-secret variables in test steps with `{{env:NAME}}`:

```yaml
steps:
  - In the task title field, enter exactly "{{env:TASK_TITLE}}".
  - Set the task status to "{{env:STATUS_IN_PROGRESS}}".
```

If a variable is missing, the step fails before execution with an unresolved template error.

## workspace.secretsFile [#workspacesecretsfile]

```yaml
workspace:
  secretsFile: .env.secrets.local
```

Description: Points agent-qa at a dotenv-style file for sensitive values.

Possible values: any non-empty workspace-relative path.

Required: yes in `agent-qa.config.yaml`.

Default: none. Keep this file out of git.

Use secrets with `{{secret:NAME}}` when a value must be inserted into an action at execution time:

```yaml
steps:
  - Fill the email field with "{{secret:LOGIN_EMAIL}}".
  - Fill the password field with "{{secret:LOGIN_PASSWORD}}".
```

Secrets are also provided to hook containers as environment variables, so hook scripts can read `process.env.TASK_API_KEY`.

## Important security note [#important-security-note]

Secret file contents are not stored as part of the run artifact. agent-qa stores metadata such as the secrets file path, load status, and secret count instead of the raw secret values.

However, secrets can still appear indirectly if the application or hook sends them through observable channels. For example, a login API call could include a password or bearer token in captured network logs, request payloads, response bodies, browser console output, screenshots, or hook stdout before redaction can help.

Use disposable credentials or credentials with strict restrictions for QA runs. Prefer short-lived accounts, isolated test workspaces, narrow API scopes, and secrets that can be rotated without affecting production users.

## .env variables [#env-variables]

```dotenv
TASK_TITLE=Release checklist review
TASK_PRIORITY=Urgent
```

Description: Non-secret runtime variables loaded before the run.

Possible values: dotenv key/value pairs.

Default: none.

## CLI --var [#cli---var]

```bash
agent-qa run --var TASK_PRIORITY=High tests/task-create-and-complete.yaml
```

Description: One-off variable override for a single command.

Possible values: `KEY=VALUE` pairs.

Default: no CLI variables.

## Suite hook variables [#suite-hook-variables]

```dotenv
WORKSPACE_ID="ws_123"
```

Description: Variables exported by suite setup hooks. They are passed to later suite hooks and tests.

Possible values: any key/value written to `/tmp/agent-qa.env` by a successful hook.

Default: no variables unless hooks export them.

## Test hook variables [#test-hook-variables]

```dotenv
TASK_FOUND="true"
TASK_ID="task_123"
```

Description: Variables exported by test setup hooks, inline hooks, or teardown hooks.

Possible values: any key/value written to `/tmp/agent-qa.env` by a successful hook.

Default: no variables unless hooks export them.

## Captured variables [#captured-variables]

```yaml
steps:
  - step: Copy the task key from the detail header.
    capture:
      variable: TASK_KEY
      method: regex
      pattern: "TASK-[0-9]+"
```

Description: Runtime values captured from a web page step and made available through `{{env:NAME}}`.

Possible values: capture variables produced by `regex`, `selector`, or `ai` capture.

Default: no captured variables.

## setVariable values [#setvariable-values]

```yaml
steps:
  - Remember the current release lane as SESSION_LABEL for later steps.
```

Description: Runtime variable set by the agent only when a step explicitly asks it to store a value.

Possible values: any non-secret runtime value.

Default: none.

## Hook output variables [#hook-output-variables]

Hooks export variables by writing dotenv content to `/tmp/agent-qa.env`:

```js
import { writeFile } from "node:fs/promises"

await writeFile(
  "/tmp/agent-qa.env",
  [
    'TASK_FOUND="true"',
    'TASK_ID="task_123"',
    "",
  ].join("\n"),
  "utf-8",
)
```

After a successful hook, later hooks and steps can read those values with `{{env:TASK_FOUND}}` and `{{env:TASK_ID}}`.

## Secret redaction boundaries [#secret-redaction-boundaries]

agent-qa redacts known secret values from hook stdout, stderr, errors, and run data where the exact value is available to the redactor. Redaction is not a license to use production credentials. If a third-party service echoes a transformed token, a session cookie, or a derived credential into logs, that value may not match the original secret exactly.

Keep test credentials scoped, disposable, and easy to rotate.