apify-test-tools 0.9.1-beta.11 → 0.9.1-beta.13

package/.github/workflows/public_push-build-latest.yaml

@@ -25,6 +25,8 @@ jobs:
               with:
                   npm-token: ${{ secrets.NPM_TOKEN }}
 
+            # --base-commit is the last commit that is already released: the push's "before" commit.
+            # Everything after it up to HEAD gets released. See the "Releasing Actors" section of the README.
             # run-with-apify-tokens.mjs reads the token names from in apify-test-tools.config.json
             # and hands the build those secrets and nothing else, so the tokens stay in this one command instead of the whole job.
             # The library never sees secrets it doesn't need
@@ -34,7 +36,7 @@ jobs:
                   SLACK_TOKEN_RELEASES_BOT: ${{ secrets.SLACK_TOKEN_RELEASES_BOT }}
               run: |
                   node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
-                    npx apify-test-tools release --push-event-path ${{ github.event_path }} --release-slack-channel "#delivery-public-actors" --report-slack-channel "${{ inputs.report-slack-channel || format('#notif-{0}', github.event.repository.name) }}" --use-docker-cache
+                    npx apify-test-tools release --base-commit ${{ github.event.before }} --release-slack-channel "#delivery-public-actors" --report-slack-channel "${{ inputs.report-slack-channel || format('#notif-{0}', github.event.repository.name) }}" --use-docker-cache
 
             - name: Delete old builds
               env:

package/.github/workflows-package-version

@@ -1 +1 @@
-0.9.0
+0.10.0

package/CHANGELOG.md

@@ -19,6 +19,7 @@ All notable changes to this project will be documented in this file.
 ### 🚜 Refactor
 
 - **workflows:** [**breaking**] Rename the floating tag to workflows-v0 ([#146](https://github.com/apify/apify-test-tools/pull/146)) ([c48fb22](https://github.com/apify/apify-test-tools/commit/c48fb223c885c4e5de7e5f64d8c14f6d03fcc7de)) by [@metalwarrior665](https://github.com/metalwarrior665)
+- **bin:** [**breaking**] Remove GitHub event dependency from release command ([#153](https://github.com/apify/apify-test-tools/pull/153)) ([e6953aa](https://github.com/apify/apify-test-tools/commit/e6953aa095d1a92638c6d72441e1b312d9f835c3)) by [@metalwarrior665](https://github.com/metalwarrior665), closes [#131](https://github.com/apify/apify-test-tools/issues/131)
 
 
 <!-- git-cliff-unreleased-end -->

package/CONTRIBUTING.md

@@ -10,7 +10,6 @@ The package consists of three parts:
 
 - `bin/build.ts` actor building
 - `bin/git.ts` git wrappers for getting relevant git commits and changed files
-- `bin/github.ts` github push event parsing
 - `bin/main.ts` entrypoing
 - `bin/slack.ts` sending notifications to slack
 - `bin/test-report.ts` processing vitest's test reports
@@ -40,12 +39,11 @@ git clone git@github.com:apify-store/testing-repo-for-github-actions.git
 
 #### Working on the CLI
 
-To work on the library, you just need to define `GITHUB_WORKSPACE` to tell the cli where you repo is located:
+To work on the library, point the cli to your repo with `--workspace` (it defaults to the current directory):
 
 ```sh
-export GITHUB_WORKSPACE=../path/to/testing-repo-for-github-actions # path to the repo
 npx tsx bin/main.ts --help
-npx tsx bin/main.ts get-commits --target-branch master --source-branch feat/testing-feature-branch
+npx tsx bin/main.ts --workspace ../path/to/testing-repo-for-github-actions get-commits --target-branch master --source-branch feat/testing-feature-branch
 ```
 
 #### Working on the library

package/README.md

@@ -12,6 +12,9 @@ npm i -D apify-test-tools
 
 - Requires `vitest` version `3.2.0` or later (uses [annotate](https://vitest.dev/guide/test-context.html#annotate))
 - Make sure `target` and `module` in your `tsconfig.json`'s `compilerOptions` are set to `ES2022`
+- Every Actor must already have at least one build under its default build tag (usually `latest`), built
+  from a Git repository version whose URL points to this repository. Build it once manually on the
+  platform before CI takes over. See [Repository check](#repository-check).
 
 ### 2. Create the config file
 
@@ -223,6 +226,10 @@ jobs:
         secrets: inherit
 ```
 
+This workflow runs `apify-test-tools release --base-commit ${{ github.event.before }}`. See
+[Releasing Actors](#releasing-actors-release) for how the released range is determined and what to
+pass if you call the CLI from somewhere else.
+
 ### `claude-review.yaml`
 
 Optional. Reviews a PR against the shared guidelines when you add the trigger label, and again on
@@ -588,7 +595,7 @@ The main local flow is:
 4. Build Actors on Apify (with your new code)
 5. Run tests against those builds. You can change tests and run on the same builds.
 
-`cd` into the actor repository you want to work with (or use `--workspace`).
+Run every command from the root of the actor repository you want to work with (or point `--workspace` at it).
 
 #### 4. Build affected Actors
 
@@ -598,7 +605,6 @@ Requires `APIFY_TOKEN_<USERNAME>` for all Apify users that own your Actors (e.g.
 
 ```bash
 APIFY_TOKEN_JOHN_DOE=<token> \
-GITHUB_WORKSPACE=. \
   npx apify-test-tools build \
     --target-branch origin/master \
     --source-branch origin/my-dummy-branch \
@@ -617,7 +623,6 @@ If you don't want to push a dummy branch just to test a change and wait for all
 
 ```bash
 APIFY_TOKEN_JOHN_DOE=<token> \
-GITHUB_WORKSPACE=. \
   npx apify-test-tools build-from-local --actors john.doe/my-actor
 ```
 
@@ -626,8 +631,7 @@ Pass a hardcoded actor name via `--actors` to build only that Actor (comma-separ
 ```bash
 # Build from local source and capture output
 BUILDS=$(APIFY_TOKEN_JOHN_DOE=apify_api_xxx \
-  GITHUB_WORKSPACE=. \
-  npx apify-test-tools build-from-local --actors apify/my-actor)
+    npx apify-test-tools build-from-local --actors apify/my-actor)
 ```
 
 Since you already scoped the build to just the Actor(s) you care about, point vitest at a specific test file (or a `-t` name filter) instead of the whole `test/platform` directory — you get feedback on that one test without waiting for the full suite to run.
@@ -649,8 +653,7 @@ TESTER_APIFY_TOKEN=<token> \
 ```bash
 # Build and capture output
 BUILDS=$(APIFY_TOKEN_JOHN_DOE=apify_api_xxx \
-  GITHUB_WORKSPACE=. \
-  npx apify-test-tools build \
+    npx apify-test-tools build \
     --target-branch origin/master \
     --source-branch origin/my-dummy-branch)
 
@@ -660,10 +663,67 @@ TESTER_APIFY_TOKEN=apify_api_yyy \
   npx vitest --run --maxConcurrency 20 --fileParallelism=true --maxWorkers 100 test/platform
 ```
 
+### Releasing Actors (`release`)
+
+`release` builds the `latest` (default) version of every Actor changed since the last release and
+posts release notes to Slack. It reads everything else from git: the branch from the checked-out
+`HEAD`, the commits and changed files from the range `<base-commit>..HEAD`, and the repository from
+the `origin` remote.
+
+```bash
+npx apify-test-tools release --base-commit <sha> --release-slack-channel "#releases" --dry-run
+```
+
+#### `--base-commit`
+
+The last commit that is **already released**. Everything after it, up to `HEAD`, is released. It is
+required: git alone can't tell which commits a push brought, and guessing wrong silently leaves Actors
+on old code.
+
+The changed files come from diffing `<base-commit>` and `HEAD` directly, so this works for every
+merge strategy as long as the base commit is the branch tip from **before** the push:
+
+| Merge strategy                 | What lands on the branch          | What to pass                                                           |
+| ------------------------------ | --------------------------------- | ---------------------------------------------------------------------- |
+| Squash and merge               | 1 new commit                      | the push's "before" commit (`HEAD~1` also works)                       |
+| Merge commit                   | the PR's commits + 1 merge commit | the push's "before" commit (`HEAD^1`, the first parent, also works)    |
+| Rebase and merge / direct push | N new commits                     | the push's "before" commit (`HEAD~1` would miss the first N-1 commits) |
+
+On GitHub, the push's "before" commit is `${{ github.event.before }}`, which the reusable workflow
+passes for you. On other CIs use the equivalent, e.g. `$CI_COMMIT_BEFORE_SHA` on GitLab. The checkout
+needs the full history (`fetch-depth: 0` in `actions/checkout`) so the base commit is available locally.
+
+`release` fails instead of guessing when:
+
+- the base commit is all zeros (GitHub sends this for a push that created the branch)
+- the base commit isn't in the local history (shallow checkout) or isn't an ancestor of `HEAD`
+  (the branch was force-pushed)
+
+In those cases, rerun `release` with a `--base-commit` you pick yourself: an ancestor of `HEAD` from
+before the changes you want to release (for a shallow checkout, fetch the full history instead).
+`--actors` only narrows which of the changed Actors get released; it never forces a build, so on its
+own it doesn't get past these errors.
+If `HEAD` is the base commit, there is nothing to release and the command exits successfully.
+
+A failed release isn't retried by the next push: that push's base commit is the failed one's head, so
+its changes are skipped. Re-run the failed workflow run, or release the Actors manually.
+
+#### Repository check
+
+`release` and `build` point each Actor's version at the `origin` remote. Because a build overwrites the
+version's Git URL, building from a fork or a mirror would repoint the Actor. So, before building, the
+remote is compared with the Git URL of the Actor's default version (the one its default build tag
+points to), and the command fails if they differ or if the default version isn't built from a Git
+repository. The URL form doesn't matter (`https://github.com/org/repo` equals
+`git@github.com:org/repo.git`).
+
+To build from a different repository on purpose, e.g. when moving an Actor, pass `--repo-url`. That
+skips the check.
+
 #### Dev mode
 
 For development on `apify-test-tools` itself, use `tsx` directly:
 
 ```bash
-GITHUB_WORKSPACE=local-clone tsx bin/main.ts get-actor-configs
+tsx bin/main.ts --workspace local-clone get-actor-configs
 ```

package/bin/build-from-local.ts

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import AdmZip from 'adm-zip';
-import type { ActorVersion } from 'apify-client';
+import type * as ApifyClientTypes from 'apify-client';
 import { ActorSourceType } from 'apify-client';
 
 import { dryRunBuildData, LOCAL_SOURCE_VERSION_NUMBER, runAndSummarizeBuilds } from './build.js';
@@ -207,7 +207,7 @@ export const runBuildsFromLocal = async ({
         for (const { name, content } of await collectSourceFiles(actorConfig.actorFullName, actorConfig.folder)) {
             zip.addFile(name, content);
         }
-        const actorVersion: ActorVersion = {
+        const actorVersion: ApifyClientTypes.ActorVersion = {
             versionNumber: LOCAL_SOURCE_VERSION_NUMBER,
             tarballUrl: await builder.uploadSourceZip(LOCAL_SOURCE_VERSION_NUMBER, zip.toBuffer()),
             sourceType: ActorSourceType.Tarball,

package/bin/build.ts

@@ -1,6 +1,7 @@
-import type { ActorVersion, Build } from 'apify-client';
+import type * as ApifyClientTypes from 'apify-client';
 import { ActorSourceType, ApifyClient } from 'apify-client';
 
+import { normalizeRepoUrl } from './git.js';
 import type { ActorConfig, BuildData } from './types.js';
 
 type BuildPrActorOptions = {
@@ -8,6 +9,7 @@ type BuildPrActorOptions = {
     versionNumber: string;
     gitRepoUrl: string;
     actorConfig: ActorConfig;
+    actorInfo: ApifyClientTypes.Actor;
     useDockerCache: boolean;
 };
 
@@ -15,51 +17,89 @@ type BuildPrActorOptions = {
 export const LOCAL_SOURCE_VERSION_NUMBER = '0.98';
 const DEFAULT_TEST_VERSION_NUMBER = '0.99';
 
+// Shown whenever an Actor isn't set up the way CI builds need it
+const ACTOR_SETUP_REQUIREMENT =
+    'Before using apify-test-tools, every Actor needs at least one build under its default build tag (usually "latest"), ' +
+    'built from a Git repository version whose URL points to this repository. Build it once manually on the platform.';
+
+/**
+ * Finds the Actor's default version: the one whose build the default build tag points to.
+ * Usually tagged 'latest' but not necessarily (can be e.g. 'version-0').
+ */
+export const resolveDefaultVersion = (actorFullName: string, actorInfo: ApifyClientTypes.Actor) => {
+    const defaultBuildTag = actorInfo.defaultRunOptions.build;
+    console.error(`Default build tag for ${actorFullName} is ${defaultBuildTag}`);
+
+    // We could technically allow this but in most cases this is accidentally set wrongly and there is a workaround
+    if (defaultBuildTag.match(/\d+\.\d+\.\d+/)) {
+        throw new Error(
+            `[${actorFullName}] Default build is a build number, not a tag. While this could work, ` +
+                `we want to have a default as tag so this is often an accidental misconfiguration from the dev`,
+        );
+    }
+    // I reported that buildNumber should probably not be optional
+    const defaultBuildNumber = actorInfo.taggedBuilds?.[defaultBuildTag]?.buildNumber;
+    if (!defaultBuildNumber) {
+        throw new Error(`[${actorFullName}] No build found for tag "${defaultBuildTag}". ${ACTOR_SETUP_REQUIREMENT}`);
+    }
+    const defaultVersionNumber = defaultBuildNumber.match(/(\d+\.\d+)\.\d+/)![1];
+    console.error(`Default version for ${actorFullName} is ${defaultVersionNumber}`);
+
+    const defaultVersion = actorInfo.versions.find((version) => version.versionNumber === defaultVersionNumber);
+
+    return { defaultBuildNumber, defaultVersionNumber, defaultBuildTag, defaultVersion };
+};
+
+/**
+ * Guards against building an Actor from a different repository than it is published from, e.g. when the
+ * local `origin` remote is a fork or a mirror. Every build overwrites the version's Git URL, so building
+ * from the wrong remote would silently repoint the Actor. The default version is the source of truth
+ * since it is what users run. Skipped when the repo URL is passed explicitly, which is how you move an
+ * Actor to a new repository on purpose.
+ */
+export const assertRepoUrlMatchesDefaultVersion = (
+    actorFullName: string,
+    defaultVersion: ApifyClientTypes.ActorVersion | undefined,
+    repoUrl: string,
+) => {
+    if (!defaultVersion) {
+        throw new Error(
+            `[${actorFullName}] The version of the default build no longer exists. ${ACTOR_SETUP_REQUIREMENT}`,
+        );
+    }
+    if (defaultVersion.sourceType !== ActorSourceType.GitRepo) {
+        throw new Error(
+            `[${actorFullName}] Default version ${defaultVersion.versionNumber} has source type "${defaultVersion.sourceType}", ` +
+                `not "${ActorSourceType.GitRepo}". ${ACTOR_SETUP_REQUIREMENT}`,
+        );
+    }
+    if (normalizeRepoUrl(defaultVersion.gitRepoUrl) !== normalizeRepoUrl(repoUrl)) {
+        throw new Error(
+            `[${actorFullName}] Repository mismatch: the git remote "origin" is ${repoUrl} but default version ` +
+                `${defaultVersion.versionNumber} is built from ${defaultVersion.gitRepoUrl}. Fix the remote or the Actor's source, ` +
+                `or pass --repo-url to build from a different repository on purpose.`,
+        );
+    }
+};
+
 export class ApifyBuilder {
     private constructor(
         private readonly apifyClient: ApifyClient,
         private readonly actorFullName: string,
     ) {}
 
-    // Usually 'latest' but not necessarily (can be e.g. 'version-0')
-    getDefaultVersionAndTag = async (): Promise<{
-        defaultBuildNumber: string;
-        defaultVersionNumber: string;
-        defaultBuildTag: string;
-    }> => {
-        const actorClient = this.apifyClient.actor(this.actorFullName);
-        const actorInfo = await actorClient.get();
-
+    getActorInfo = async (): Promise<ApifyClientTypes.Actor> => {
+        const actorInfo = await this.apifyClient.actor(this.actorFullName).get();
         if (!actorInfo) {
             throw new Error(
                 `[${this.actorFullName}] not found. It is not published or we are missing token to access it privately or its name is misspelled`,
             );
         }
-
-        const defaultBuildTag = actorInfo.defaultRunOptions.build;
-        console.error(`Default build tag for ${this.actorFullName} is ${defaultBuildTag}`);
-
-        // We could technically allow this but in most cases this is accidentally set wrongly and there is a workaround
-        if (defaultBuildTag.match(/\d+\.\d+\.\d+/)) {
-            throw new Error(
-                `[${this.actorFullName}] Default build is a build number, not a tag. While this could work, ` +
-                    `we want to have a default as tag so this is often an accidental misconfiguration from the dev`,
-            );
-        }
-        // I reported that buildNumber should probably not be optional
-        if (!actorInfo.taggedBuilds?.[defaultBuildTag]?.buildNumber) {
-            throw new Error(
-                `[${this.actorFullName}] No build found for tag "${defaultBuildTag}". ` +
-                    `The first build must be triggered manually on the platform before CI can take over.`,
-            );
-        }
-        const defaultBuildNumber = actorInfo.taggedBuilds![defaultBuildTag].buildNumber!;
-        const defaultVersionNumber = defaultBuildNumber.match(/(\d+\.\d+)\.\d+/)![1];
-        console.error(`Default version for ${this.actorFullName} is ${defaultVersionNumber}`);
-
-        return { defaultBuildNumber, defaultVersionNumber, defaultBuildTag };
+        return actorInfo;
     };
 
+    getDefaultVersionAndTag = async () => resolveDefaultVersion(this.actorFullName, await this.getActorInfo());
+
     // Mirrors `apify push`: stores the zip in the Actor's `actor-<id>-source` KV store and returns a signed
     // record URL the builder can download without a token.
     uploadSourceZip = async (versionNumber: string, zip: Buffer): Promise<string> => {
@@ -76,24 +116,19 @@ export class ApifyBuilder {
         return url.toString();
     };
 
+    // Pass actorInfo when the caller already fetched it, to save an API call
     createVersionAndBuild = async (
         versionNumber: string,
-        actorVersion: ActorVersion,
+        actorVersion: ApifyClientTypes.ActorVersion,
         useCache: boolean,
+        actorInfo?: ApifyClientTypes.Actor,
     ): Promise<BuildData> => {
         const actorClient = this.apifyClient.actor(this.actorFullName);
-        const actorInfo = await actorClient.get();
-        if (!actorInfo) {
-            throw new Error(
-                `No actor named '${this.actorFullName}' was found on the platform. If this` +
-                    ' is unexpected, make sure the actor you are targeting is spelled the' +
-                    ' same as the folder in the repository.',
-            );
-        }
+        const { versions } = actorInfo ?? (await this.getActorInfo());
 
         // Prepare version
-        const versionExists = !actorInfo.versions.find((version) => version.versionNumber === versionNumber);
-        if (versionExists) {
+        const versionMissing = !versions.find((version) => version.versionNumber === versionNumber);
+        if (versionMissing) {
             // create new version
             await actorClient.versions().create(actorVersion);
         } else {
@@ -108,7 +143,7 @@ export class ApifyBuilder {
         return { buildId: id, actorRawId: actId, buildNumber, actorFullName: this.actorFullName };
     };
 
-    waitForBuildToFinish = async (buildId: string): Promise<Build> => {
+    waitForBuildToFinish = async (buildId: string): Promise<ApifyClientTypes.Build> => {
         const build = await this.apifyClient.build(buildId).waitForFinish();
         const versionNumber = build.buildNumber;
         if (build.status === 'FAILED' || build.status === 'TIMED-OUT') {
@@ -168,7 +203,7 @@ export class ApifyBuilder {
         const DEFAULT_DAYS_BACK_PROD_VERSIONS = 30;
         const DEFAULT_DAYS_BACK_DEVEL = 7;
 
-        const actorInfo = (await this.apifyClient.actor(this.actorFullName).get())!;
+        const actorInfo = await this.getActorInfo();
 
         // 'devel' used to be hardcoded for testing version 0.99, once we get rid of this tag everywhere, we can remove this code
         const taggedDevelBuildNumber: string | undefined = actorInfo.taggedBuilds!.devel?.buildNumber;
@@ -183,7 +218,7 @@ export class ApifyBuilder {
         const { items } = await this.apifyClient.actor(this.actorFullName).builds().list();
 
         // Deleting default build throws an error, so we skip it
-        const { defaultBuildNumber, defaultBuildTag } = await this.getDefaultVersionAndTag();
+        const { defaultBuildNumber, defaultBuildTag } = resolveDefaultVersion(this.actorFullName, actorInfo);
 
         const daysAgoUnixProd = Date.now() - DEFAULT_DAYS_BACK_PROD_VERSIONS * 24 * 60 * 60 * 1000;
         const daysAgoUnixDevel = Date.now() - DEFAULT_DAYS_BACK_DEVEL * 24 * 60 * 60 * 1000;
@@ -286,6 +321,8 @@ type RunBuildsOptions = {
     actorConfigs: ActorConfig[];
     isLatest?: boolean;
     repoUrl: string;
+    // False when the repo URL was passed explicitly, see assertRepoUrlMatchesDefaultVersion
+    shouldVerifyRepoUrl: boolean;
     branch: string;
     dryRun: boolean;
     useDockerCache: boolean;
@@ -293,34 +330,40 @@ type RunBuildsOptions = {
 
 export const runBuilds = async ({
     repoUrl,
+    shouldVerifyRepoUrl,
     branch,
     actorConfigs,
     isLatest = false,
     dryRun,
     useDockerCache,
 }: RunBuildsOptions): Promise<BuildData[]> => {
-    const buildConfigs: BuildPrActorOptions[] = [];
-
-    for (const actorConfig of actorConfigs) {
-        let versionNumber: string;
-        let buildTag: string | undefined;
-
-        if (isLatest) {
-            const { defaultVersionNumber, defaultBuildTag } =
-                await ApifyBuilder.fromActorConfig(actorConfig).getDefaultVersionAndTag();
-            versionNumber = defaultVersionNumber;
-            buildTag = defaultBuildTag;
-        } else {
-            versionNumber = DEFAULT_TEST_VERSION_NUMBER;
-        }
+    // 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) => {
+            const actorInfo = await ApifyBuilder.fromActorConfig(actorConfig).getActorInfo();
+            const { defaultVersionNumber, defaultBuildTag, defaultVersion } = resolveDefaultVersion(
+                actorConfig.actorFullName,
+                actorInfo,
+            );
+            if (shouldVerifyRepoUrl) {
+                assertRepoUrlMatchesDefaultVersion(actorConfig.actorFullName, defaultVersion, repoUrl);
+            }
 
-        // Depending on if these are miniactors or standaloneActors
-        let gitRepoUrl = `${repoUrl}#${branch}`;
-        if (actorConfig.folder) {
-            gitRepoUrl = `${gitRepoUrl}:${actorConfig.folder}`;
-        }
-        buildConfigs.push({ actorConfig, gitRepoUrl, versionNumber, buildTag, useDockerCache });
-    }
+            // Depending on if these are miniactors or standaloneActors
+            let gitRepoUrl = `${repoUrl}#${branch}`;
+            if (actorConfig.folder) {
+                gitRepoUrl = `${gitRepoUrl}:${actorConfig.folder}`;
+            }
+            return {
+                actorConfig,
+                actorInfo,
+                gitRepoUrl,
+                versionNumber: isLatest ? defaultVersionNumber : DEFAULT_TEST_VERSION_NUMBER,
+                buildTag: isLatest ? defaultBuildTag : undefined,
+                useDockerCache,
+            };
+        }),
+    );
 
     if (dryRun) {
         console.error('[DRY RUN] Would build:');
@@ -338,18 +381,19 @@ export const runBuilds = async ({
 
     return runAndSummarizeBuilds(actorConfigs, 'BUILDS', async (actorConfig, builder) => {
         const {
+            actorInfo,
             buildTag,
             versionNumber,
             gitRepoUrl,
             useDockerCache: useCache,
         } = buildConfigsByActorFullName.get(actorConfig.actorFullName)!;
-        const actorVersion: ActorVersion = {
+        const actorVersion: ApifyClientTypes.ActorVersion = {
             buildTag,
             versionNumber,
             gitRepoUrl,
             sourceType: ActorSourceType.GitRepo,
         };
-        return builder.createVersionAndBuild(versionNumber, actorVersion, useCache);
+        return builder.createVersionAndBuild(versionNumber, actorVersion, useCache, actorInfo);
     });
 };
 

package/bin/git.ts

@@ -145,3 +145,143 @@ export const parseCommit = (commitString: string): Commit => {
         message,
     };
 };
+
+/**
+ * Returns the currently checked-out branch. Release builds point the Actor version at this branch,
+ * so a detached HEAD (no branch to point at) is an error rather than a guess.
+ */
+export const getCurrentBranch = (): string => {
+    const branch = spawnCommandInGhWorkspace('git rev-parse --abbrev-ref HEAD');
+    if (branch === 'HEAD') {
+        throw new Error(
+            'Cannot determine the branch to release: HEAD is detached. Check out the branch you want to release.',
+        );
+    }
+    return branch;
+};
+
+/**
+ * Reads the repository URL from the `origin` remote, rewritten to the SSH form the Apify platform
+ * uses for Git repo sources, e.g. git@github.com:apify-store/google-maps
+ */
+const getOriginRepoUrl = (): string => {
+    return spawnCommandInGhWorkspace('git remote get-url origin').replace(
+        /^https:\/\/github\.com\//,
+        'git@github.com:',
+    );
+};
+
+/**
+ * Picks the repo URL to build from. By default it's the `origin` remote, and runBuilds then checks it against
+ * each Actor's default version, so a fork or mirror remote can't repoint a published Actor. An explicit
+ * --repo-url skips that check: passing it is how you move an Actor to another repository on purpose.
+ */
+export const resolveRepoUrl = (explicitRepoUrl: string | undefined) => ({
+    repoUrl: explicitRepoUrl ?? getOriginRepoUrl(),
+    shouldVerifyRepoUrl: explicitRepoUrl === undefined,
+});
+
+/**
+ * Makes repo URLs comparable regardless of their form. All of these normalize to `github.com/org/repo`:
+ * - git@github.com:org/repo.git
+ * - https://github.com/org/repo
+ * - ssh://git@github.com/org/repo#master:actors/foo (Actor versions carry a `#branch:folder` fragment)
+ */
+export const normalizeRepoUrl = (repoUrl: string): string => {
+    return repoUrl
+        .trim()
+        .split('#')[0]
+        .replace(/^[a-z+]+:\/\//i, '')
+        .replace(/^[^@/]+@/, '')
+        .replace(':', '/')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/, '')
+        .toLowerCase();
+};
+
+/** Repository name from its URL, e.g. `google-maps` for git@github.com:apify-store/google-maps.git */
+export const getRepoName = (repoUrl: string): string => {
+    return normalizeRepoUrl(repoUrl).split('/').pop()!;
+};
+
+// Sent by e.g. GitHub as the "before" commit of a push that created the branch
+const ZERO_SHA_REGEX = /^0{40}$/;
+
+/**
+ * Validates the base commit of a release: the last commit whose changes are already released.
+ * Unlike the PR path (getCommits), there is no lenient fallback. Falling back to "everything"
+ * would rebuild the latest build of every Actor and post it to Slack, so every problem is an error.
+ */
+export const resolveReleaseBaseCommit = (baseCommit: string): string => {
+    const sha = parseBaseCommit(baseCommit);
+    if (!sha) {
+        throw new Error('--base-commit is required for release. See the README section "Releasing Actors".');
+    }
+    if (ZERO_SHA_REGEX.test(sha)) {
+        throw new Error(
+            `Base commit is ${sha}, which means the branch was just created and there is no previous release to diff against. ` +
+                `Rerun with --base-commit set to the last commit before the changes you want to release.`,
+        );
+    }
+    // --quiet makes rev-parse print nothing (instead of an error) when the commit is missing
+    if (!spawnCommandInGhWorkspace(`git rev-parse --verify --quiet "${sha}^{commit}"`)) {
+        throw new Error(
+            `Base commit ${sha} is not in the local git history. Either the checkout is shallow ` +
+                `(fetch the full history, e.g. fetch-depth: 0 in actions/checkout) or the branch was force-pushed.`,
+        );
+    }
+    // git merge-base A B outputs the common ancestor. If that equals A, then A is an ancestor of B.
+    if (spawnCommandInGhWorkspace(`git merge-base ${sha} HEAD`) !== sha) {
+        throw new Error(
+            `Base commit ${sha} is not an ancestor of HEAD, most likely because the branch was force-pushed. ` +
+                `The changed files cannot be determined reliably. Rerun with --base-commit set to an ancestor of HEAD ` +
+                `from before the changes you want to release.`,
+        );
+    }
+    return sha;
+};
+
+const CHANGELOG_PATH = 'CHANGELOG.md';
+
+/** Returns the lines added to the root CHANGELOG.md between baseSha and HEAD, or null if it didn't change. */
+const getChangelogAdditions = (baseSha: string, changedFiles: string[]): string | null => {
+    if (!changedFiles.includes(CHANGELOG_PATH)) {
+        return null;
+    }
+    const diff = spawnCommandInGhWorkspace('git', ['diff', baseSha, 'HEAD', '--', CHANGELOG_PATH]);
+
+    const added: string[] = [];
+    let startedChangelog = false;
+    for (const line of diff.split('\n')) {
+        // The diff is already limited to the changelog but better to double check
+        if (line.startsWith('+++') && line.toLowerCase().includes(CHANGELOG_PATH.toLowerCase())) {
+            startedChangelog = true;
+            continue;
+        }
+        if (startedChangelog) {
+            if (line.startsWith('diff')) {
+                break;
+            }
+            if (line.startsWith('+')) {
+                added.push(line.slice(1).trim());
+            }
+        }
+    }
+    return added.join('\n').trim();
+};
+
+/**
+ * Everything that changed since the last release (baseSha, exclusive) up to HEAD, or null when there
+ * are no new commits. Changed files come from diffing the range directly instead of from the commit
+ * list: with a merge commit, the oldest commit of the merged branch can be older than baseSha, and
+ * diffing from its parent would pull in already-released changes.
+ */
+export const getReleaseChanges = (baseSha: string) => {
+    if (spawnCommandInGhWorkspace('git rev-parse HEAD') === baseSha) {
+        return null;
+    }
+    const commits = fetchAllBranchCommits('HEAD', baseSha);
+    const changedFiles = spawnCommandInGhWorkspace(`git diff --name-only ${baseSha} HEAD`).split('\n').filter(Boolean);
+    const changelog = getChangelogAdditions(baseSha, changedFiles);
+    return { commits, changedFiles, changelog };
+};