feat: add --apply-env-vars-to-build flag to push (#734) (#1345)

Part of #734 (the `applyEnvVarsToBuild` toggle half).

## What
- New `--apply-env-vars-to-build` boolean flag on `apify push` — sets
`applyEnvVarsToBuild: true` on the Actor version, so env vars from
`actor.json` are also available during the Docker build.
`--no-apply-env-vars-to-build` explicitly turns the setting off.
- When the flag is omitted, the field is left out of the API payload
entirely, so a value previously set in Console is **preserved** (pushes
to existing Actors don't reset it).
- Flag-parser tweak: `_parseFlags` matched provided flags by truthiness.
The real CLI path is unaffected (`multiple: true` means values always
arrive as arrays, which are truthy), but
`testRunCommand`/`internalRunCommand` inject scalar values, where an
explicit `false` was silently dropped. The matcher now checks for
presence, and the required-flag check is aligned to `undefined`, so
harness-injected negated booleans behave the same as parsed ones (the
new test relies on this).
- Regenerated `docs/` via `pnpm run update-docs`.

## Why
Env vars synced by `apify push` currently apply only at runtime; making
them apply to the build requires flipping a switch in Console. That
breaks CI and fresh pushes of Actors that need build-time secrets (e.g.
a GitHub token as a Docker build arg).

## Tests
- New `[api]` test in `test/api/commands/push.test.ts` covering: flag →
`true`, omitted → preserved, negated flag → `false`. Full push API suite
passes (13/13), plus `test:local`, lint, format, build.

## Follow-ups (separate PRs)
- `applyEnvVarsToBuild` field in `.actor/actor.json` (#1346, stacked on
this).
- `--env KEY=VALUE` passing on push (the other half of #734).

No new dependencies; no install-size impact.

Co-authored-by: Richard Solar <solar.richard@gmail.com>

Author: MatousMarik

docs/reference.md

@@ -788,8 +788,8 @@ DESCRIPTION
 
 USAGE
   $ apify actors push [actorId] [--allow-missing-secrets]
-                      [-b <value>] [--dir <value>] [-f] [--json] [--open]
-                      [-v <value>] [-w <value>]
+                      [--apply-env-vars-to-build] [-b <value>] [--dir <value>]
+                      [-f] [--json] [--open] [-v <value>] [-w <value>]
 
 ARGUMENTS
   actorId  Name or ID of the Actor to push (e.g. "apify/hello-world" or
@@ -800,6 +800,11 @@ FLAGS
       --allow-missing-secrets    Allow the command to
                                  continue even when secret values are not found in
                                  the local secrets storage.
+      --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.
   -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.

src/commands/actors/push.ts

@@ -223,6 +223,11 @@ export class ActorsPushCommand extends ApifyCommand<typeof ActorsPushCommand> {
 			required: false,
 			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.',
+			required: false,
+		}),
 	};
 
 	static override args = {
@@ -454,9 +459,11 @@ 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;
 
 		if (actorCurrentVersion) {
-			const actorVersionModifier = { tarballUrl, sourceFiles, buildTag, sourceType, envVars };
+			const actorVersionModifier = { tarballUrl, sourceFiles, buildTag, sourceType, envVars, applyEnvVarsToBuild };
 			// TODO: fix this type too -.-
 			await actorClient.version(version).update(actorVersionModifier as never);
 			run({ message: `Updated version ${version} for Actor ${actor.name}.` });
@@ -468,6 +475,7 @@ Skipping push. Use --force to override.`,
 				buildTag,
 				sourceType,
 				envVars,
+				applyEnvVarsToBuild,
 			};
 
 			await actorClient.versions().create({

src/lib/command-framework/apify-command.ts

@@ -523,7 +523,7 @@ export abstract class ApifyCommand<T extends typeof BuiltApifyCommand = typeof B
 
 			let rawFlag = rawFlags[matchingFlags[0]];
 
-			if (!rawFlag && builderData.required) {
+			if (typeof rawFlag === 'undefined' && builderData.required) {
 				throw new CommandError({
 					code: CommandErrorCode.APIFY_MISSING_FLAG,
 					command: this.ctor,

test/api/commands/push.test.ts

@@ -215,6 +215,52 @@ describe('[api] apify push', () => {
 		TEST_TIMEOUT,
 	);
 
+	it(
+		'should set applyEnvVarsToBuild when the flag is passed and keep it when omitted',
+		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'));
+
+			await testRunCommand(ActorsPushCommand, {
+				args_actorId: testActor.id,
+				flags_noPrompt: true,
+				flags_force: true,
+				flags_applyEnvVarsToBuild: true,
+			});
+
+			const versionWithFlag = await testActorClient.version(actorJson.version).get();
+
+			await testRunCommand(ActorsPushCommand, {
+				args_actorId: testActor.id,
+				flags_noPrompt: true,
+				flags_force: true,
+			});
+
+			const versionWithoutFlag = await testActorClient.version(actorJson.version).get();
+
+			// false is what --no-apply-env-vars-to-build parses to
+			await testRunCommand(ActorsPushCommand, {
+				args_actorId: testActor.id,
+				flags_noPrompt: true,
+				flags_force: true,
+				flags_applyEnvVarsToBuild: false,
+			});
+
+			const versionWithNegatedFlag = await testActorClient.version(actorJson.version).get();
+
+			await testActorClient.delete();
+
+			expect(versionWithFlag!.applyEnvVarsToBuild).to.be.eql(true);
+			// omitting the flag must preserve the value stored on the platform
+			expect(versionWithoutFlag!.applyEnvVarsToBuild).to.be.eql(true);
+			// the negated flag must actively turn the setting off
+			expect(versionWithNegatedFlag!.applyEnvVarsToBuild).to.be.eql(false);
+		},
+		TEST_TIMEOUT,
+	);
+
 	it(
 		'should upload zip for source files larger that 3MB',
 		async () => {