Skip to content

environment.md

Latest commit

 

History

History
109 lines (76 loc) · 4.02 KB

environment.md

File metadata and controls

109 lines (76 loc) · 4.02 KB

Environment Variables and Secrets

This guide covers the full details of how FinalRun resolves environment variables, secrets, and AI provider API keys. For a quick summary, see the README. For workspace config and app identity, see configuration.md.

Where to Put Files

Workspace root is the folder that contains .finalrun/. FinalRun finds it by walking up from your shell's current directory, so dotenv paths are anchored to that root (not to cwd when you run from a subfolder).

my-app/                    # workspace root
  .env                     # optional; shared defaults (do not commit)
  .env.dev                 # optional; values when using env name "dev" (do not commit)
  .finalrun/
    config.yaml
    env/
      dev.yaml             # declares placeholder bindings only
    tests/
      smoke.yaml

Dotenv files (secrets and provider keys)

  • .env — optional; values merged for all runs (see load order below).
  • .env.<name> — optional; used when that environment is active (e.g. .env.dev for --env dev or env: dev in .finalrun/config.yaml). The name matches .finalrun/env/<name>.yaml.

Binding files (.finalrun/env/<name>.yaml)

Declares secrets as placeholders like ${TEST_USER_EMAIL} and variables as plain values. The CLI resolves each secrets placeholder from the shell environment and from workspace-root .env / .env.<name>. Do not put real secrets inside this YAML.

secrets:
  email: ${TEST_USER_EMAIL}
  password: ${TEST_USER_PASSWORD}

variables:
  locale: en-US

Load Order

For a resolved environment name N, the CLI loads variables in this order:

  1. .env.N — environment-specific dotenv file
  2. .env — fills in any keys not already set
  3. process.env — wins if the same name is set in both a file and the shell environment

This single workspace-root dotenv setup is used for:

  • Resolving secrets mappings declared in .finalrun/env/*.yaml (from ${ENV_VAR} placeholders), which are referenced as ${secrets.*} in test specs.
  • Reading AI provider API keys (OPENAI_API_KEY, GOOGLE_API_KEY, ANTHROPIC_API_KEY) for finalrun test and finalrun suite.

When no FinalRun environment is in use (env-free workspace), the CLI does not require a .env.N file for YAML bindings; you can still use process.env or .env for keys if applicable.

AI Provider API Keys

FinalRun resolves API keys by provider prefix:

Provider prefix Environment variable
openai/... OPENAI_API_KEY
google/... GOOGLE_API_KEY
anthropic/... ANTHROPIC_API_KEY

Keys are read from process.env and from workspace-root .env / .env.<name>. You can also pass --api-key to override.

Git: Keep Secrets Out of the Repo

Do not commit .env files. Add the following to your app repository's .gitignore:

.env
.env.*
!.env.example

This ignores .env, .env.dev, .env.staging, and similar while keeping .env.example tracked as a template.

Platform Prerequisites (Detailed)

Required for Android local runs

  • adb available through ANDROID_HOME, ANDROID_SDK_ROOT, or PATH
  • emulator on PATH; the current Android preflight requires it to discover and boot Android Virtual Devices
  • scrcpy on PATH — required by FinalRun for Android screen recording during local runs
  • FinalRun Android driver assets — bundled automatically by the published CLI during installation

Required for iOS local runs

  • macOS
  • Xcode command line tools with xcrun
  • xcrun simctl
  • unzip
  • /bin/bash
  • plutil
  • Bundled FinalRun iOS driver archives present; the published CLI installs them automatically

Optional helpers

  • ffmpeg compresses iOS recordings after capture
  • applesimutils enables simulator permission helpers
  • lsof, ps, and kill help with stale iOS driver cleanup

Verify local host readiness with:

finalrun doctor
finalrun doctor --platform android
finalrun doctor --platform ios