feat: read applyEnvVarsToBuild from actor.json in push (#734) (#1346)

Part of #734, stacked on #1345 (retarget to `master` once that merges —
only the last commit is new here).

## What
- `apify push` now reads `applyEnvVarsToBuild` from `.actor/actor.json`,
so the setting persists per repo and applies on every push (useful for
CI and Actors needing build-time secrets).
- Precedence: `--[no-]apply-env-vars-to-build` flag >
`applyEnvVarsToBuild` in actor.json > omitted (value stored on the
platform is kept). An explicit `false` in actor.json turns the setting
off.
- Documented in `docs/vars.md`; flag description updated (+ regenerated
`docs/reference.md`).

## Tests
- New `[api]` test covering field `true`, field `false`, flag-over-field
precedence, and the negated flag beating a `true` in the file (the case
that pins `??` over `||`). Full push API suite passes (14/14), plus
`test:local`, lint, format, build.
- Note for reviewers: `useActorConfig` caches by cwd, so the test resets
the cache when rewriting actor.json mid-test.

## Follow-up (separate PR)
- `--env KEY=VALUE` passing on push (the other half of #734).

No new dependencies; no install-size impact.

---------

Co-authored-by: Edyta <142720610+szaganek@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Richard Solár <solar.richard@gmail.com>

Author: 4 people

docs/reference.md

@@ -803,8 +803,11 @@ FLAGS
       --apply-env-vars-to-build  Make the environment
                                  variables also available to the Actor build
                                  process. Use --no-apply-env-vars-to-build to turn
-                                 the setting off. When omitted, the setting
-                                 currently stored on the platform is kept.
+                                 the setting off. Overrides the value of the
+                                 'applyEnvVarsToBuild' field in the
+                                 '.actor/actor.json' file. When both the field and
+                                 the flag are omitted, the setting currently stored
+                                 on the platform is kept.
   -b, --build-tag=<value>        Build tag to be
                                  applied to the successful Actor build. By default,
                                  it is taken from the '.actor/actor.json' file.

docs/vars.md

@@ -74,3 +74,22 @@ You can use the CLI to manage secrets environment variables:
         ...
     }
     ```
+
+### Apply environment variables to the build
+
+By default, custom environment variables are available only at runtime. To make them available also to the Actor build process, for example, as Docker build arguments, set `applyEnvVarsToBuild` in `.actor/actor.json`:
+
+```json
+{
+  "actorSpecification": 1,
+  "name": "dataset-to-mysql",
+  "version": "0.1",
+  "buildTag": "latest",
+  "applyEnvVarsToBuild": true,
+  "environmentVariables": {
+    "MYSQL_PASSWORD": "@mySecretPassword"
+  }
+}
+```
+
+To apply the environment variables to a single push, add the `--apply-env-vars-to-build` flag to the `apify push` command. To turn off the setting for a single push, add the `--no-apply-env-vars-to-build` flag. The flag overrides the value of the `applyEnvVarsToBuild` field. If you use neither the field nor a flag, the Apify platform keeps the stored setting.

src/commands/actors/push.ts

@@ -224,8 +224,7 @@ export class ActorsPushCommand extends ApifyCommand<typeof ActorsPushCommand> {
 			default: false,
 		}),
 		'apply-env-vars-to-build': Flags.boolean({
-			description:
-				'Make the environment variables also available to the Actor build process. Use --no-apply-env-vars-to-build to turn the setting off. When omitted, the setting currently stored on the platform is kept.',
+			description: `Make the environment variables also available to the Actor build process. Use --no-apply-env-vars-to-build to turn the setting off. Overrides the value of the 'applyEnvVarsToBuild' field in the '${LOCAL_CONFIG_PATH}' file. When both the field and the flag are omitted, the setting currently stored on the platform is kept.`,
 			required: false,
 		}),
 	};
@@ -459,8 +458,10 @@ Skipping push. Use --force to override.`,
 					allowMissing: this.flags.allowMissingSecrets,
 				})
 			: undefined;
-		// true/false when --[no-]apply-env-vars-to-build is passed, undefined when omitted so the value stored on the platform is preserved
-		const { applyEnvVarsToBuild } = this.flags;
+		// The flag wins when passed, then the actor.json field; undefined when neither is set, so the value
+		// stored on the platform is preserved
+		const applyEnvVarsToBuild =
+			this.flags.applyEnvVarsToBuild ?? (actorConfig!.applyEnvVarsToBuild as boolean | undefined);
 
 		if (actorCurrentVersion) {
 			const actorVersionModifier = { tarballUrl, sourceFiles, buildTag, sourceType, envVars, applyEnvVarsToBuild };

test/api/commands/push.test.ts

@@ -261,6 +261,76 @@ describe('[api] apify push', () => {
 		TEST_TIMEOUT,
 	);
 
+	it(
+		'should read applyEnvVarsToBuild from actor.json, with the flag taking precedence',
+		async () => {
+			const testActor = await testUserClient.actors().create(TEST_ACTOR);
+			actorsForCleanup.add(testActor.id);
+			const testActorClient = testUserClient.actor(testActor.id);
+			const actorJson = JSON.parse(readFileSync(joinPath(LOCAL_CONFIG_PATH), 'utf8'));
+
+			try {
+				actorJson.applyEnvVarsToBuild = true;
+				writeFileSync(joinPath(LOCAL_CONFIG_PATH), JSON.stringify(actorJson, null, '\t'), { flag: 'w' });
+
+				await testRunCommand(ActorsPushCommand, {
+					args_actorId: testActor.id,
+					flags_noPrompt: true,
+					flags_force: true,
+				});
+
+				const versionWithFieldTrue = await testActorClient.version(actorJson.version).get();
+
+				actorJson.applyEnvVarsToBuild = false;
+				writeFileSync(joinPath(LOCAL_CONFIG_PATH), JSON.stringify(actorJson, null, '\t'), { flag: 'w' });
+				// the actor config is cached per cwd, so mid-test rewrites need a reset
+				resetCwdCaches();
+
+				await testRunCommand(ActorsPushCommand, {
+					args_actorId: testActor.id,
+					flags_noPrompt: true,
+					flags_force: true,
+				});
+
+				const versionWithFieldFalse = await testActorClient.version(actorJson.version).get();
+
+				// the file still says false, but the flag must win
+				await testRunCommand(ActorsPushCommand, {
+					args_actorId: testActor.id,
+					flags_noPrompt: true,
+					flags_force: true,
+					flags_applyEnvVarsToBuild: true,
+				});
+
+				const versionWithFlagOverride = await testActorClient.version(actorJson.version).get();
+
+				// and the negated flag must also win over a true in the file
+				actorJson.applyEnvVarsToBuild = true;
+				writeFileSync(joinPath(LOCAL_CONFIG_PATH), JSON.stringify(actorJson, null, '\t'), { flag: 'w' });
+				resetCwdCaches();
+
+				await testRunCommand(ActorsPushCommand, {
+					args_actorId: testActor.id,
+					flags_noPrompt: true,
+					flags_force: true,
+					flags_applyEnvVarsToBuild: false,
+				});
+
+				const versionWithNegatedFlagOverride = await testActorClient.version(actorJson.version).get();
+
+				expect(versionWithFieldTrue!.applyEnvVarsToBuild).to.be.eql(true);
+				expect(versionWithFieldFalse!.applyEnvVarsToBuild).to.be.eql(false);
+				expect(versionWithFlagOverride!.applyEnvVarsToBuild).to.be.eql(true);
+				expect(versionWithNegatedFlagOverride!.applyEnvVarsToBuild).to.be.eql(false);
+			} finally {
+				delete actorJson.applyEnvVarsToBuild;
+				writeFileSync(joinPath(LOCAL_CONFIG_PATH), JSON.stringify(actorJson, null, '\t'), { flag: 'w' });
+				await testActorClient.delete();
+			}
+		},
+		TEST_TIMEOUT,
+	);
+
 	it(
 		'should upload zip for source files larger that 3MB',
 		async () => {