Env & Secrets

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

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

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

workspace.envFile

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}}:

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

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:

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

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

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

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

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

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

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

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

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

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

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.