apify-test-tools 0.10.2-beta.1 → 0.10.2-beta.10

package/bin/affected-actors.ts

@@ -0,0 +1,198 @@
+import { type ChangedActors, getChangedActors } from './diff-changes.js';
+import {
+    findCommitSha,
+    getChangedFilesBetween,
+    getChangelogAdditions,
+    getCommitsBetween,
+    getMergeBase,
+    resolveCommitSha,
+    resolveReleaseBaseCommit,
+} from './git.js';
+import { logger } from './logger.js';
+import type { ActorConfig, Commit, GitRange } from './types.js';
+import { readConfigFile } from './utils/config/load-config.js';
+
+// The range always ends at the checked-out commit: check out what you want to inspect
+const HEAD = 'HEAD';
+
+interface AffectedActorsOptions {
+    /**
+     * Base usually points to the master branch
+     * Only what HEAD changes compared to base counts, like `git diff base...HEAD` or GitHub's "Files changed" tab:
+     * the branch's own changes, not what it merged in from base.
+     */
+    base?: string;
+    /**
+     * With `base` it's the last validated commit of the branch: Actors that didn't change after it are left out.
+     * It's ignored when it is HEAD (a rerun) or isn't in the local history. Without `base` everything after it
+     * counts, and it must be an ancestor of HEAD (e.g. the last release).
+     */
+    since?: string;
+    /** Glob relative to the repo root. Matching files count as changes even when .dockerignore lists them. */
+    testFilesGlob?: string;
+    actors: string[];
+    ignore: string[];
+}
+
+/** The JSON document `get-affected-actors` prints. Versioned, since other commands and workflows consume it. */
+interface AffectedActors {
+    version: 1;
+    head: string;
+    /** The commits, changed files and changelog describe the whole range, `--since` with `--base` only narrows the Actors. */
+    commits: Commit[];
+    changedFiles: string[];
+    changelog: string | null;
+    /**
+     * Actors with at least one functional change. They need a new build and tests. Only the names: the config file
+     * stays the source of truth for the rest.
+     */
+    functionallyChangedActors: { actorFullName: string }[];
+    /** Actors whose changes are all cosmetic (README, CHANGELOG, cosmetic .actor JSON). They only need a release build. */
+    cosmeticallyChangedActors: { actorFullName: string }[];
+}
+
+const names = (configs: ActorConfig[]) => configs.map(({ actorFullName }) => ({ actorFullName }));
+
+/** The branch's last validated commit, unless it can't narrow anything down. */
+const findValidatedSha = async (since: string, headSha: string): Promise<string | undefined> => {
+    const sinceSha = await findCommitSha(since);
+    if (!sinceSha) {
+        logger.info(
+            `Last validated commit ${since} is not in the local history (force-push?), checking the whole branch`,
+        );
+        return undefined;
+    }
+    if (sinceSha === headSha) {
+        logger.info('Last validated commit is HEAD, so this is a rerun: checking the whole branch from scratch');
+        return undefined;
+    }
+    return sinceSha;
+};
+
+/**
+ * This is Juan's magical algorithm where we need just 2 git diffs to determine functional changes on Actors.
+ *
+ * Naively, we could just check branch HEAD changes vs base or parent of first commit and be done but
+ * we do this jiu-jitsu code to apply 2 optimizations:
+ * 1. On our PR branch, we track last validated commit (since) that was tested and so we only need to test new commits.
+ * 2. We also merge changes from the base branch (usually master) and we can consider those already validated as well.
+ *
+ * But there is annoying problem: even if both our branch and base are validated, they could have novel interactions and
+ * we need to retest those.
+ *
+ * So we look at:
+ * 1. The changes introduced by our branch since the last validated commit (`since..HEAD`).
+ * 2. The changes introduced by the branch compared to the base branch (`base...HEAD`). The important part is that this
+ * diff does check the whole branch, discarding the last validated commit (since) so it checks those novel interactions problem.
+ *
+ * The magic is that both need to contain changes for an Actor to be retested:
+ * 1. If we have changes only in since..HEAD (and not in base...HEAD), it means those changes came from merging the base alone
+ * which is already validated and there were actually no real changes introduced by our branch alone.
+ * 2. If we have changes only in base...HEAD (and not in since..HEAD), it means there are no new changes on our branch
+ * since it was last validated. base...HEAD has changes that we already validated.
+ *
+ * This enables to simply do those 2 diffs for each Actor's context separately and only Actors that have changes
+ * in both diffs need to be retested.
+ *
+ * THIS ASSUMES BRANCH IS UP TO DATE WITH BASE WHEN IT MERGES, which we currently require. Only then is HEAD what lands on
+ * base, and base's commits validated. Otherwise what lands is HEAD combined with base's newer commits, which nobody
+ * tested, however the Actors are picked.
+ *
+ * In each example the branch's functional change to Actor A was validated at `since`, then one more push follows:
+ *
+ * Example scenarios:
+ * - Our own branch only: a commit changes A's README and B's code.
+ *   `since..HEAD`: A cosmetic, B functional. `base...HEAD`: A and B functional.
+ *   → A cosmetic, B functional: only B is tested, A's code is still the validated one.
+ * - Cosmetic merge: the branch merges base, which only changed READMEs and the CHANGELOG.
+ *   `since..HEAD`: every Actor cosmetic (CHANGELOG counts for all). `base...HEAD`: A functional, since the merged
+ *   files now match base and drop out of it.
+ *   → A cosmetic, the other Actors left out: nothing is tested.
+ * - Functional merge: the branch merges base, which changed code of A and of C.
+ *   `since..HEAD`: A and C functional. `base...HEAD`: A functional.
+ *   → A functional, C left out: A is tested, since base's change can interact with the branch's, while C only has
+ *   base's change, which base already validated.
+ */
+const intersectChangedInBranchVsSince = (branch: ChangedActors, sinceValidated: ChangedActors): ChangedActors => {
+    const narrowed: ChangedActors = { functional: [], cosmetic: [] };
+    // All checks are done for each Actor separately, that's cleanest and most accurate
+    for (const actor of [...branch.functional, ...branch.cosmetic]) {
+        // base...HEAD
+        const changedFunctionallyOnBranch = branch.functional.includes(actor);
+        // since..HEAD
+        const changedFunctionallySince = sinceValidated.functional.includes(actor);
+
+        // changedSince is used for release. Release cares also about cosmetic.
+        const changedSince = changedFunctionallySince || sinceValidated.cosmetic.includes(actor);
+
+        // Nothing changed since the last validation, so the branch's change to this Actor is already validated
+        if (!changedSince) continue;
+
+        // As we said, only intersection counts as functional, otherwise it's cosmetic
+        if (changedFunctionallyOnBranch && changedFunctionallySince) {
+            narrowed.functional.push(actor);
+        } else {
+            narrowed.cosmetic.push(actor);
+        }
+    }
+    return narrowed;
+};
+
+/**
+ * Finds the Actors whose context changed in the given range. `base` selects the branch's own changes
+ * (a PR), `since` the changes after a known commit (a release, or the last validated commit of a PR).
+ */
+export const getAffectedActors = async ({
+    base,
+    since: sinceOption,
+    testFilesGlob,
+    actors,
+    ignore,
+}: AffectedActorsOptions): Promise<AffectedActors> => {
+    // An empty --since (e.g. an empty cache file) means the same as not passing it
+    const since = sinceOption || undefined;
+    if (!base && !since) {
+        throw new Error('Pass --base, --since, or both to select the commits to inspect.');
+    }
+
+    const actorConfigs = await readConfigFile({ actors, ignore });
+    const getChangedInRange = async (range: GitRange) => {
+        const changedFiles = await getChangedFilesBetween(range.fromRef, range.toRef);
+        return {
+            changedFiles,
+            changedActors: await getChangedActors({
+                filepathsChanged: changedFiles,
+                actorConfigs,
+                range,
+                testFilesGlob,
+            }),
+        };
+    };
+
+    const headSha = await resolveCommitSha(HEAD);
+    const rangeVsBase: GitRange = {
+        // merge base = PR, release base = push to master (release)
+        fromRef: base ? await getMergeBase(base, HEAD) : await resolveReleaseBaseCommit(since!),
+        toRef: headSha,
+    };
+
+    // Falls back to rangeVsBase.fromRef when there's no (usable) last validated commit — same as
+    // intersecting the branch's changes with themselves, which is a no-op (see this function's docs).
+    const validatedSha = base && since ? await findValidatedSha(since, headSha) : undefined;
+    const sinceFromRef = validatedSha ?? rangeVsBase.fromRef;
+
+    const { changedFiles, changedActors: changedVsBase } = await getChangedInRange(rangeVsBase);
+    const { changedActors: changedSinceActors } = await getChangedInRange({ fromRef: sinceFromRef, toRef: headSha });
+    // See this function's docs to understand the algorithm: only intersection counts as functional, otherwise it's cosmetic.
+    const changedActors = intersectChangedInBranchVsSince(changedVsBase, changedSinceActors);
+
+    return {
+        version: 1,
+        head: headSha,
+        commits: await getCommitsBetween(rangeVsBase.fromRef, rangeVsBase.toRef),
+        changedFiles,
+        changelog: await getChangelogAdditions(rangeVsBase.fromRef, rangeVsBase.toRef, changedFiles),
+        functionallyChangedActors: names(changedActors.functional),
+        cosmeticallyChangedActors: names(changedActors.cosmetic),
+    };
+};

package/bin/build-from-local.ts

@@ -6,11 +6,17 @@ import AdmZip from 'adm-zip';
 import type * as ApifyClientTypes from 'apify-client';
 import { ActorSourceType } from 'apify-client';
 
-import { dryRunBuildData, LOCAL_SOURCE_VERSION_NUMBER, runAndSummarizeBuilds } from './build.js';
+import {
+    ApifyBuilder,
+    assertEnvVarsMatchDefaultVersion,
+    LOCAL_SOURCE_VERSION_NUMBER,
+    resolveDefaultVersion,
+    runAndSummarizeBuilds,
+} from './build.js';
 import { loadDockerIgnore } from './dockerignore.js';
 import { logger } from './logger.js';
 import { isPathWithinScope } from './path-utils.js';
-import type { ActorConfig, BuildData } from './types.js';
+import type { ActorConfig, BuildData, DryRunPlan } from './types.js';
 import type { SourceFile } from './utils.js';
 import { getGitignoredPaths, isOutsideDir, listRepoFilePaths, readSourceFile } from './utils.js';
 import type { RelativeDir } from './utils/path/repo-relative.js';
@@ -179,32 +185,78 @@ export const rewriteActorJsonPaths = async (
     await fs.writeFile(path.join(newActorDir, 'actor.json'), JSON.stringify(rewritten, null, 4));
 };
 
+type LocalBuildPlan = {
+    actorFullName: string;
+    versionNumber: string;
+    folder: string;
+    fileCount: number;
+    zipSizeBytes: number;
+};
+
 export const runBuildsFromLocal = async ({
     actorConfigs,
     dryRun,
+    requireEnvVarsInSync = false,
 }: {
     actorConfigs: ActorConfig[];
     dryRun: boolean;
-}): Promise<BuildData[]> => {
+    // See assertEnvVarsMatchDefaultVersion
+    requireEnvVarsInSync?: boolean;
+}): Promise<BuildData[] | DryRunPlan<LocalBuildPlan>> => {
+    // Read-only preparation shared with the real build, so a dry run fails on a missing token, an unknown
+    // Actor or unreadable sources just like the build would
+    const preparedBuilds = await Promise.all(
+        actorConfigs.map(async (actorConfig) => {
+            const actorInfo = await ApifyBuilder.fromActorConfig(actorConfig).getActorInfo();
+            if (requireEnvVarsInSync) {
+                const { defaultVersion } = resolveDefaultVersion(actorConfig.actorFullName, actorInfo);
+                assertEnvVarsMatchDefaultVersion(
+                    actorConfig.actorFullName,
+                    actorInfo,
+                    defaultVersion,
+                    LOCAL_SOURCE_VERSION_NUMBER,
+                );
+            }
+            // Zipped and uploaded like `apify push` does, since inline SOURCE_FILES are capped at ~9 MB.
+            const zip = new AdmZip();
+            const sourceFiles = await collectSourceFiles(actorConfig);
+            for (const { name, content } of sourceFiles) {
+                zip.addFile(name, content);
+            }
+            return { actorConfig, actorInfo, fileCount: sourceFiles.length, zipBuffer: zip.toBuffer() };
+        }),
+    );
+
     if (dryRun) {
         logger.info('[DRY RUN] Would build from local source:');
-        for (const { actorFullName, folder } of actorConfigs) {
-            logger.info(`  ${actorFullName} (${folder})`);
+        for (const { actorConfig, fileCount, zipBuffer } of preparedBuilds) {
+            logger.info(
+                `  ${actorConfig.actorFullName} (${actorConfig.folder}): ${fileCount} files, ${zipBuffer.length} bytes zipped`,
+            );
         }
-        return actorConfigs.map(({ actorFullName }) => dryRunBuildData(actorFullName, LOCAL_SOURCE_VERSION_NUMBER));
+        return {
+            dryRun: true,
+            builds: preparedBuilds.map(({ actorConfig, fileCount, zipBuffer }) => ({
+                actorFullName: actorConfig.actorFullName,
+                versionNumber: LOCAL_SOURCE_VERSION_NUMBER,
+                folder: actorConfig.folder.path,
+                fileCount,
+                zipSizeBytes: zipBuffer.length,
+            })),
+        };
     }
 
+    const preparedByActorFullName = new Map(
+        preparedBuilds.map((prepared) => [prepared.actorConfig.actorFullName, prepared]),
+    );
+
     return runAndSummarizeBuilds(actorConfigs, 'LOCAL BUILDS', async (actorConfig, builder) => {
-        // Zipped and uploaded like `apify push` does, since inline SOURCE_FILES are capped at ~9 MB.
-        const zip = new AdmZip();
-        for (const { name, content } of await collectSourceFiles(actorConfig)) {
-            zip.addFile(name, content);
-        }
+        const { actorInfo, zipBuffer } = preparedByActorFullName.get(actorConfig.actorFullName)!;
         const actorVersion: ApifyClientTypes.ActorVersion = {
             versionNumber: LOCAL_SOURCE_VERSION_NUMBER,
-            tarballUrl: await builder.uploadSourceZip(LOCAL_SOURCE_VERSION_NUMBER, zip.toBuffer()),
+            tarballUrl: await builder.uploadSourceZip(LOCAL_SOURCE_VERSION_NUMBER, zipBuffer),
             sourceType: ActorSourceType.Tarball,
         };
-        return builder.createVersionAndBuild(LOCAL_SOURCE_VERSION_NUMBER, actorVersion, false);
+        return builder.createVersionAndBuild(LOCAL_SOURCE_VERSION_NUMBER, actorVersion, false, actorInfo);
     });
 };

package/bin/build.ts

@@ -1,22 +1,21 @@
 import type * as ApifyClientTypes from 'apify-client';
 import { ActorSourceType, ApifyClient } from 'apify-client';
 
-import { normalizeRepoUrl } from './git.js';
+import { getCurrentBranch, normalizeRepoUrl, resolveRepoUrl } from './git.js';
 import { logger } from './logger.js';
-import type { ActorConfig, BuildData } from './types.js';
+import type { ActorConfig, BuildData, DryRunPlan } from './types.js';
 
 type BuildPrActorOptions = {
-    buildTag?: string;
     versionNumber: string;
     gitRepoUrl: string;
     actorConfig: ActorConfig;
     actorInfo: ApifyClientTypes.Actor;
-    useDockerCache: boolean;
 };
 
 // Fixed version number used to build from local source files, since there is no real version to track.
 export const LOCAL_SOURCE_VERSION_NUMBER = '0.98';
-const DEFAULT_TEST_VERSION_NUMBER = '0.99';
+// Stands for each Actor's default version: the one its default build tag points to
+export const DEFAULT_VERSION_KEYWORD = 'default';
 
 // Shown whenever an Actor isn't set up the way CI builds need it
 const ACTOR_SETUP_REQUIREMENT =
@@ -83,6 +82,44 @@ export const assertRepoUrlMatchesDefaultVersion = (
     }
 };
 
+const getEnvVarNames = (version: ApifyClientTypes.ActorVersion | undefined): string[] =>
+    (version?.envVars ?? []).map(({ name }) => name).filter((name): name is string => !!name);
+
+/**
+ * Guards against testing an Actor with different env vars than users run it with, e.g. a variable added to
+ * the default version but not to the test version, which would make the tests pass or fail for the wrong
+ * reason. Only names are compared because the API doesn't return secret values.
+ */
+export const assertEnvVarsMatchDefaultVersion = (
+    actorFullName: string,
+    actorInfo: ApifyClientTypes.Actor,
+    defaultVersion: ApifyClientTypes.ActorVersion | undefined,
+    versionNumber: string,
+) => {
+    if (!defaultVersion) {
+        throw new Error(
+            `[${actorFullName}] The version of the default build no longer exists. ${ACTOR_SETUP_REQUIREMENT}`,
+        );
+    }
+    const version = actorInfo.versions.find((v) => v.versionNumber === versionNumber);
+    const defaultNames = getEnvVarNames(defaultVersion);
+    const names = getEnvVarNames(version);
+    const missing = defaultNames.filter((name) => !names.includes(name));
+    const extra = names.filter((name) => !defaultNames.includes(name));
+    if (missing.length === 0 && extra.length === 0) return;
+
+    const differences = [
+        missing.length > 0 ? `missing ${missing.join(', ')}` : undefined,
+        extra.length > 0 ? `extra ${extra.join(', ')}` : undefined,
+    ].filter(Boolean);
+    throw new Error(
+        `[${actorFullName}] Env vars of version ${versionNumber} are out of sync with default version ` +
+            `${defaultVersion.versionNumber} (${differences.join('; ')}). ` +
+            `${version ? '' : `Version ${versionNumber} doesn't exist yet, so create it on the platform first. `}` +
+            `Add or remove the env vars in version ${versionNumber} so their names match the default version's.`,
+    );
+};
+
 export class ApifyBuilder {
     private constructor(
         private readonly apifyClient: ApifyClient,
@@ -179,7 +216,7 @@ export class ApifyBuilder {
      * Deletes build of all versions. Apify API doesn't allow to delete default build and we explicitly skip it
      * We delete devel builds faster because we used the for every PR until recently so just to get rid of them faster
      */
-    async deleteOldBuilds(): Promise<void> {
+    async deleteOldBuilds({ dryRun }: { dryRun: boolean }): Promise<void> {
         // Even though we don't version our current Actors, if we ever such Actors to GitHub CI, we would accidentally delete old supported versions
         // This hardcoded solution is not ideal, but it should prevent most imaginable cases
         // All currently popular versioned Actors use `version-${number}` format
@@ -258,9 +295,15 @@ export class ApifyBuilder {
         });
 
         logger.info(
-            `[DELETE OLD BUILDS][${this.actorFullName}]: Deleting ${buildsToDelete.length} old builds that are non-default and ` +
-                `older than 30 days from total ${items.length}`,
+            `[DELETE OLD BUILDS][${this.actorFullName}]: ${dryRun ? '[DRY RUN] Would delete' : 'Deleting'} ${buildsToDelete.length} ` +
+                `old builds that are non-default and older than 30 days from total ${items.length}`,
         );
+        if (dryRun) {
+            for (const build of buildsToDelete) {
+                logger.info(`  ${build.buildNumber} (${build.id}, started ${build.startedAt.toISOString()})`);
+            }
+            return;
+        }
         for (const build of buildsToDelete) {
             await this.apifyClient.build(build.id).delete();
         }
@@ -310,23 +353,23 @@ export const runAndSummarizeBuilds = async (
     return waitAndSummarizeBuilds(startedBuilds, buildersByActorFullName, label);
 };
 
-// Placeholder BuildData for dry runs, since no real build was triggered.
-export const dryRunBuildData = (actorFullName: string, versionNumber: string): BuildData => ({
-    buildId: 'dry-run',
-    actorRawId: 'dry-run',
-    buildNumber: versionNumber,
-    actorFullName,
-});
+type GitBuildPlan = {
+    actorFullName: string;
+    versionNumber: string;
+    gitRepoUrl: string;
+};
 
 type RunBuildsOptions = {
     actorConfigs: ActorConfig[];
-    isLatest?: boolean;
+    // A version number like "0.99", or DEFAULT_VERSION_KEYWORD for each Actor's default version
+    versionNumber: string;
     repoUrl: string;
     // False when the repo URL was passed explicitly, see assertRepoUrlMatchesDefaultVersion
     shouldVerifyRepoUrl: boolean;
     branch: string;
     dryRun: boolean;
-    useDockerCache: boolean;
+    // See assertEnvVarsMatchDefaultVersion
+    requireEnvVarsInSync?: boolean;
 };
 
 export const runBuilds = async ({
@@ -334,10 +377,10 @@ export const runBuilds = async ({
     shouldVerifyRepoUrl,
     branch,
     actorConfigs,
-    isLatest = false,
+    versionNumber,
     dryRun,
-    useDockerCache,
-}: RunBuildsOptions): Promise<BuildData[]> => {
+    requireEnvVarsInSync = false,
+}: RunBuildsOptions): Promise<BuildData[] | DryRunPlan<GitBuildPlan>> => {
     // Fetched once per Actor and reused for the checks, the version numbers and the build itself
     const buildConfigs: BuildPrActorOptions[] = await Promise.all(
         actorConfigs.map(async (actorConfig) => {
@@ -346,9 +389,28 @@ export const runBuilds = async ({
                 actorConfig.actorFullName,
                 actorInfo,
             );
+            // Builds keep the tags their version gives them, so a default version without the default build tag
+            // would build fine but leave users on the previous build
+            if (versionNumber === DEFAULT_VERSION_KEYWORD && defaultVersion?.buildTag !== defaultBuildTag) {
+                logger.warn(
+                    `[${actorConfig.actorFullName}] Default version ${defaultVersionNumber} has build tag ` +
+                        `"${defaultVersion?.buildTag ?? 'none'}", not "${defaultBuildTag}", so users keep running the previous build. ` +
+                        'Set the build tag of the version on the platform to change that.',
+                );
+            }
             if (shouldVerifyRepoUrl) {
                 assertRepoUrlMatchesDefaultVersion(actorConfig.actorFullName, defaultVersion, repoUrl);
             }
+            const targetVersionNumber =
+                versionNumber === DEFAULT_VERSION_KEYWORD ? defaultVersionNumber : versionNumber;
+            if (requireEnvVarsInSync) {
+                assertEnvVarsMatchDefaultVersion(
+                    actorConfig.actorFullName,
+                    actorInfo,
+                    defaultVersion,
+                    targetVersionNumber,
+                );
+            }
 
             // Depending on if these are miniactors or standaloneActors
             let gitRepoUrl = `${repoUrl}#${branch}`;
@@ -359,21 +421,23 @@ export const runBuilds = async ({
                 actorConfig,
                 actorInfo,
                 gitRepoUrl,
-                versionNumber: isLatest ? defaultVersionNumber : DEFAULT_TEST_VERSION_NUMBER,
-                buildTag: isLatest ? defaultBuildTag : undefined,
-                useDockerCache,
+                versionNumber: targetVersionNumber,
             };
         }),
     );
 
+    // Everything above only reads, so a dry run has checked what the real run would, short of writing
     if (dryRun) {
         logger.info('[DRY RUN] Would build:');
-        for (const { actorConfig, versionNumber } of buildConfigs) {
-            logger.info(`  ${actorConfig.actorFullName} (${versionNumber})`);
+        const builds = buildConfigs.map((buildConfig) => ({
+            actorFullName: buildConfig.actorConfig.actorFullName,
+            versionNumber: buildConfig.versionNumber,
+            gitRepoUrl: buildConfig.gitRepoUrl,
+        }));
+        for (const build of builds) {
+            logger.info(`  ${build.actorFullName} (${build.versionNumber}) from ${build.gitRepoUrl}`);
         }
-        return buildConfigs.map(({ actorConfig, versionNumber }) =>
-            dryRunBuildData(actorConfig.actorFullName, versionNumber),
-        );
+        return { dryRun: true, builds };
     }
 
     const buildConfigsByActorFullName = new Map(
@@ -381,25 +445,43 @@ export const runBuilds = async ({
     );
 
     return runAndSummarizeBuilds(actorConfigs, 'BUILDS', async (actorConfig, builder) => {
-        const {
-            actorInfo,
-            buildTag,
-            versionNumber,
-            gitRepoUrl,
-            useDockerCache: useCache,
-        } = buildConfigsByActorFullName.get(actorConfig.actorFullName)!;
+        const buildConfig = buildConfigsByActorFullName.get(actorConfig.actorFullName)!;
+        // No buildTag: the version keeps the one it has, so its build gets the tag the version already gives it
         const actorVersion: ApifyClientTypes.ActorVersion = {
-            buildTag,
-            versionNumber,
-            gitRepoUrl,
+            versionNumber: buildConfig.versionNumber,
+            gitRepoUrl: buildConfig.gitRepoUrl,
             sourceType: ActorSourceType.GitRepo,
         };
-        return builder.createVersionAndBuild(versionNumber, actorVersion, useCache, actorInfo);
+        // Always with the Docker cache: CI always asked for it, and a clean build can still be started on the platform
+        return builder.createVersionAndBuild(buildConfig.versionNumber, actorVersion, true, buildConfig.actorInfo);
+    });
+};
+
+type BuildActorsOptions = Omit<RunBuildsOptions, 'repoUrl' | 'shouldVerifyRepoUrl' | 'branch'> & {
+    // Defaults to the `origin` remote, see resolveRepoUrl
+    repoUrl?: string;
+};
+
+/**
+ * Builds exactly the given Actors from the checked-out Git branch, as it is on the remote. Fails on a detached HEAD,
+ * where there is no branch to build. Used by `build` and the commands built on top of it.
+ */
+export const buildActors = async ({ actorConfigs, repoUrl, ...options }: BuildActorsOptions) => {
+    if (actorConfigs.length === 0) {
+        logger.info('No Actors to build');
+        // Still the dry-run shape in a dry run, so it can't pass for a real (empty) result
+        return options.dryRun ? { dryRun: true as const, builds: [] } : [];
+    }
+    return runBuilds({
+        ...options,
+        ...(await resolveRepoUrl(repoUrl)),
+        actorConfigs,
+        branch: await getCurrentBranch(),
     });
 };
 
-export const deleteOldBuilds = async (actorConfigs: ActorConfig[]) => {
+export const deleteOldBuilds = async (actorConfigs: ActorConfig[], { dryRun }: { dryRun: boolean }) => {
     for (const actorConfig of actorConfigs) {
-        await ApifyBuilder.fromActorConfig(actorConfig).deleteOldBuilds();
+        await ApifyBuilder.fromActorConfig(actorConfig).deleteOldBuilds({ dryRun });
     }
 };