Managed Secrets
Encrypted, tiered, and injected at build time.
Central E2E test variables
Choose Secrets → E2E test variables, select an environment, and use Add variable to save test-only values under Global or your profile’s environment. Use the exact variable names from your test files; no Maestro-specific prefix is required. Newly saved variables are used automatically, with no portal profile mapping or enablement form. Managed iOS runners need MACH CLI 2.13.0 or later for private test output handling.
Managed CI run using centrally stored test values
mach maestro --latest --platform ios --profile e2e --wait
Precedence is explicit --maestro-env values, then the selected profile’s environment secrets, then Global E2E secrets. The CLI resolves inheritance and platform-specific environment overrides from mach.config.json; when environment is omitted, it uses the same profile-name scope fallback as builds. Dashboard runs use the environment recorded with the build. Older builds can use their existing legacy mapping or be tested from the linked CLI project. Scoped secrets are never resolved by guessing when context is missing. Requested variable names are checked before runner launch or billing. Automatic attempts keep one encrypted snapshot; a newly queued rerun resolves current values.
Test values are encrypted and isolated from application build variables, mach env pull and environment exports. Developers see resolved names and their environment; only administrators can change values. There is no reveal or export action. Change history records actors, names and times without values. Existing legacy configurations and explicit pauses remain unchanged until an administrator saves variables with the new workflow or chooses Use automatically. Queued and running tests are unchanged.
Updated runners scrub known values and common encodings from streamed logs, errors and textual reports. An incompatible runner cannot retrieve central values. Screenshots and recordings cannot be reliably redacted; authenticated-run evidence requires developer or higher project access and uses expiring file links. Use sample test accounts and avoid logging secrets or placing them in screenshots. Local --local runs continue to use local variables and do not download stored test credentials. No new scheduler or publishing permission is created by this feature.
Secrets are stored encrypted in the Mach Dashboard and injected into builds as environment variables. They never touch disk during builds — injected via RAM only.
The resolved environment is part of Mach's build fingerprint. Development, staging, and production builds therefore get separate native build cache keys when their injected variables differ, preventing one environment's secrets from leaking into another build.
How It Works
Encrypted at Rest
All secrets are encrypted in the Dashboard database. Only decrypted at build time.
Environment Tiers
Scope secrets by environment — development, staging, production. Each build profile maps to a tier.
RAM-Only Injection
Secrets are exported as shell variables during build. Never written to .env files on build machines.
Setting Secrets
Set a single secret
mach env set API_URL=https://api.myapp.com
Set multiple at once
mach env set API_URL=https://api.myapp.com SENTRY_DSN=https://sentry.io/123
Downloading Secrets Locally
Use `mach env pull` when a developer needs a local `.env.local` file for app startup, debugging, or simulator testing. The file contains global secrets plus the selected environment's overrides.
Development secrets to .env.local
Specific environment
mach env pull --environment staging
Custom output file
mach env pull --environment production --out .env.production.local
Replace an existing file
mach env pull --environment development --out .env.local --overwrite
`mach env download` and `mach env export` are aliases for the same command. Keep downloaded dotenv files out of git.
Android Keystore Passwords
For maximum security, your Android Keystore (.jks) file is stored separately from its passwords. To provide your passwords to the Cloud Builder, define them as environment secrets. mach will rigorously decrypt and inject them just-in-time during the signing step.
Master password (used for both Keystore and Key Alias)
mach env set KEYSTORE_PASSWORD_PRODUCTION=my_super_secret_password
Split Keystore and Key Alias passwords
mach env set KEYSTORE_PASSWORD_PRODUCTION=my_key_pass KEYSTORE_STORE_PASSWORD_PRODUCTION=my_store_pass
Injection Priority
When multiple sources define the same variable, Mach resolves them in this order (highest priority last):
1. Process env
Base environment variables from the system.
2. Dashboard secrets
Managed secrets fetched from the Dashboard API.
3. Project config
Values from mach.config.json root (prefixed MACH_).
4. Profile config
Values from the resolved build profile (prefixed MACH_PROFILE_).
5. Profile env
Explicit env vars in the profile (highest priority).
Secrets are mapped by the environment field in your build profile. Set "environment": "production" to pull production secrets during production builds.
Global vs. Environment Overrides
Under Secrets, choose Build variables and use the Environment dropdown to view Global, Development, Staging, Production or a custom scope. Global values provide defaults; environment values override matching names. E2E test variables use the same interface with separate storage. Add variable opens an inline editor. Importing a .env file fills editable rows immediately. You can also paste an entire .env block into a variable name or value field, or use Paste .env. Review each row’s name, value, visibility and environments before saving. Existing scopes are skipped unless you choose Replace. Edit a saved variable to change its environment; leaving its value empty keeps the encrypted value. A move is blocked when the destination already has that name. Export and selection actions stay in the three-dot menu.
Global environment
Values available to ALL build profiles. Use this for your single Android JKS password.
Environment overrides
Values specific to a profile. These OVERRIDE Global values with the same name.
Global is a shared default, so selecting it clears specific environments. Selecting Development, Staging and Production keeps three explicit scopes; it does not convert to Global or apply to future environments. Environment-specific values still override Global. Use another row for a different value in another environment. Imports never silently overwrite existing variables, and a partial save keeps only unsaved entries available to retry. E2E imports always remain encrypted and cannot be exported.
Naming Conventions
Do **not** include suffixes like `_PRODUCTION` in your secret names (e.g. use `API_URL`, not `API_URL_PRODUCTION`). Mach handles the environment mapping using each variable’s selected scope.
Deleting Secrets
Owners and Admins can remove a variable using its three-dot menu. This is useful for rotating keys or clearing out invalid/broken records.
If the API returns a permission error while setting or deleting secrets, check that the logged-in user or access token has Owner or Admin access to the selected project.
