apify-test-tools 0.9.1-beta.9 → 0.10.1-beta.0

package/.github/actions/checkout-restore-dependencies/action.yaml

@@ -1,13 +1,6 @@
 name: Checkout and restore dependencies
 description: Checkout and restore dependencies
 inputs:
-    working-directory:
-        description: Working directory
-        required: false
-        default: .
-    additional-working-directory:
-        description: Additional working directory
-        required: false
     npm-token:
         description: >-
             Token for installing private npm packages. Exported as both NPM_TOKEN (what a
@@ -60,30 +53,12 @@ runs:
           id: check-dependencies-cache
           uses: actions/cache@v5
           with:
-              path: ${{ inputs.working-directory }}/node_modules
-              key: modules-npm-${{ inputs.working-directory }}-${{ hashFiles(format('{0}/package-lock.json', inputs.working-directory)) }}
-
-        - name: Cache additional dependencies npm
-          id: check-additional-dependencies-cache
-          if: inputs.additional-working-directory != ''
-          uses: actions/cache@v5
-          with:
-              path: ${{ inputs.additional-working-directory }}/node_modules
-              key: modules-npm-${{ inputs.additional-working-directory }}-${{ hashFiles(format('{0}/package-lock.json', inputs.additional-working-directory)) }}
+              path: node_modules
+              key: modules-npm-${{ hashFiles('package-lock.json') }}
 
         - name: install npm dependencies
           if: steps.check-dependencies-cache.outputs.cache-hit != 'true'
           shell: bash
-          working-directory: ${{ inputs.working-directory }}
-          env:
-              NPM_TOKEN: ${{ inputs.npm-token }}
-              NODE_AUTH_TOKEN: ${{ inputs.npm-token }}
-          run: npm ci
-
-        - name: install additional npm dependencies
-          if: inputs.additional-working-directory != '' && steps.check-additional-dependencies-cache.outputs.cache-hit != 'true'
-          shell: bash
-          working-directory: ${{ inputs.additional-working-directory }}
           env:
               NPM_TOKEN: ${{ inputs.npm-token }}
               NODE_AUTH_TOKEN: ${{ inputs.npm-token }}
@@ -96,7 +71,6 @@ runs:
           # Needs the npm token too: a repo whose .npmrc routes all traffic through a private
           # registry has to authenticate even for public packages.
           shell: bash
-          working-directory: ${{ inputs.working-directory }}
           env:
               NPM_TOKEN: ${{ inputs.npm-token }}
               NODE_AUTH_TOKEN: ${{ inputs.npm-token }}

package/.github/workflows/_move_major_tag.yaml

@@ -16,6 +16,13 @@ on:
                 description: Commit to move the tag to. Defaults to the commit that triggered the caller.
                 type: string
                 default: ''
+            wait_for_publish:
+                description: >-
+                    Set by a release that has just published the pinned version. npm accepts a publish
+                    before the version is readable, so the check waits instead of treating the gap as
+                    a held tag, and fails if the version never appears.
+                type: boolean
+                default: false
 
 permissions:
     contents: read
@@ -58,23 +65,50 @@ jobs:
 
             - name: Check the required package version is published
               id: check
+              env:
+                  # npm accepts a publish and processes it asynchronously ("Your package is being
+                  # processed and may take a few minutes to become available"). Observed at ~19
+                  # minutes for a provenance-signed release, so the release path waits well past
+                  # npm's own estimate rather than shipping a tag consumers cannot install against.
+                  WAIT_SECONDS: ${{ inputs.wait_for_publish && 2400 || 0 }}
               run: |
                   pinned_version=$(cat .github/workflows-package-version)
                   echo "pinned_version=$pinned_version" >> "$GITHUB_OUTPUT"
 
-                  # The publish that satisfies a pin bump can still be in flight when this runs, so
-                  # give it a short grace period before deciding the tag has to stay put.
-                  for attempt in 1 2 3 4 5 6; do
-                      if npm view "apify-test-tools@$pinned_version" version >/dev/null 2>&1; then
+                  deadline=$(( $(date +%s) + WAIT_SECONDS ))
+                  while :; do
+                      # --prefer-online so a 404 cached from an earlier attempt cannot outlive the
+                      # publish it was polling for.
+                      if output=$(npm view "apify-test-tools@$pinned_version" version --prefer-online 2>&1); then
                           echo "apify-test-tools@$pinned_version is on npm"
                           echo "published=true" >> "$GITHUB_OUTPUT"
                           exit 0
                       fi
-                      echo "apify-test-tools@$pinned_version is not on npm yet (attempt $attempt/6)"
-                      if [ "$attempt" -lt 6 ]; then sleep 20; fi
+
+                      # Anything that is not "this version does not exist" is a registry, network or
+                      # auth problem. Sitting in the retry loop would hide it behind a held tag.
+                      if ! grep -q 'code E404' <<< "$output"; then
+                          echo "::error::npm view failed for a reason other than the version being absent."
+                          echo "$output"
+                          exit 1
+                      fi
+
+                      if [ "$(date +%s)" -ge "$deadline" ]; then
+                          break
+                      fi
+                      echo "apify-test-tools@$pinned_version is not on npm yet, retrying in 30s"
+                      sleep 30
                   done
+
                   echo "published=false" >> "$GITHUB_OUTPUT"
 
+                  # A release waited for its own publish and never saw it. That is a broken release,
+                  # not a held tag, and it has to be red so it can be re-run once npm catches up.
+                  if [ "$WAIT_SECONDS" -gt 0 ]; then
+                      echo "::error::apify-test-tools@$pinned_version was published by this run but is still not readable after $((WAIT_SECONDS / 60))m. Re-run this job once it appears on npm."
+                      exit 1
+                  fi
+
             - name: Move tag
               if: steps.check.outputs.published == 'true'
               env:

package/.github/workflows/manual_release_stable.yaml

@@ -91,3 +91,4 @@ jobs:
         uses: ./.github/workflows/_move_major_tag.yaml
         with:
             ref: ${{ needs.release_metadata.outputs.changelog_commitish }}
+            wait_for_publish: true

package/.github/workflows/public_platform-tests.yaml

@@ -13,13 +13,6 @@ on:
                 type: string
                 default: ''
                 required: false
-            working-directory:
-                type: string
-                default: .
-                required: false
-            additional-working-directory:
-                type: string
-                required: false
             # Defaults to #notif-<repo-name> when empty, matching the previous behavior.
             report-slack-channel:
                 type: string
@@ -31,16 +24,11 @@ jobs:
         name: Scheduled Platform tests
         if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main'
         runs-on: ubuntu-latest
-        defaults:
-            run:
-                working-directory: ${{ inputs.working-directory }}
         steps:
             - name: Setup repository and dependencies
               # For testing, you have to temporarily change the branch
               uses: apify/apify-test-tools/.github/actions/checkout-restore-dependencies@workflows-v0
               with:
-                  working-directory: ${{ inputs.working-directory }}
-                  additional-working-directory: ${{ inputs.additional-working-directory }}
                   npm-token: ${{ secrets.NPM_TOKEN }}
 
             - name: Test

package/.github/workflows/public_pr-build-test.yaml

@@ -3,13 +3,6 @@ name: Test
 on:
     workflow_call:
         inputs:
-            working-directory:
-                type: string
-                default: .
-                required: false
-            additional-working-directory:
-                type: string
-                required: false
             skip-platform-tests:
                 type: boolean
                 default: false
@@ -28,17 +21,12 @@ jobs:
     platformTest:
         if: ${{ !inputs.skip-platform-tests }}
         runs-on: ubuntu-latest
-        defaults:
-            run:
-                working-directory: ${{ inputs.working-directory }}
         steps:
             - name: Setup repository and dependencies
               id: setup
               # For testing, you have to temporarily change the branch
               uses: apify/apify-test-tools/.github/actions/checkout-restore-dependencies@workflows-v0
               with:
-                  working-directory: ${{ inputs.working-directory }}
-                  additional-working-directory: ${{ inputs.additional-working-directory }}
                   # Some repos use private npm packages, they need to pass NPM_TOKEN secret to this workflow
                   npm-token: ${{ secrets.NPM_TOKEN }}
 
@@ -87,13 +75,9 @@ jobs:
                   # environment variables rather than being interpolated into it.
                   HEAD_REF: ${{ github.head_ref }}
                   BASE_REF: ${{ github.base_ref }}
-                  WORKING_DIRECTORY: ${{ inputs.working-directory }}
               run: |
-                  work_dir="$WORKING_DIRECTORY"
-                  [ "$work_dir" = "." ] && work_dir=""
-                  prefix="${work_dir:+$work_dir/}test/platform/"
-                  changed=$(git diff --name-only --diff-filter=d "origin/$BASE_REF...HEAD" -- "$prefix" \
-                    | sed "s|^$prefix|./test/platform/|" | tr '\n' ' ')
+                  changed=$(git diff --name-only --diff-filter=d "origin/$BASE_REF...HEAD" -- test/platform/ \
+                    | sed "s|^|./|" | tr '\n' ' ')
                   branch_actors=$(npx apify-test-tools get-affected-actors \
                     --source-branch "origin/$HEAD_REF" \
                     --target-branch "origin/$BASE_REF")
@@ -135,17 +119,11 @@ jobs:
     unitTest:
         # TODO: only run on changes to code
         runs-on: ubuntu-latest
-        defaults:
-            run:
-                working-directory: ${{ inputs.working-directory }}
-
         steps:
             - name: Setup repository and dependencies
               # For testing, you have to temporarily change the branch
               uses: apify/apify-test-tools/.github/actions/checkout-restore-dependencies@workflows-v0
               with:
-                  working-directory: ${{ inputs.working-directory }}
-                  additional-working-directory: ${{ inputs.additional-working-directory }}
                   npm-token: ${{ secrets.NPM_TOKEN }}
 
             - name: TypeScript

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

@@ -3,13 +3,6 @@ name: Build latest and report to slack
 on:
     workflow_call:
         inputs:
-            working-directory:
-                type: string
-                default: .
-                required: false
-            additional-working-directory:
-                type: string
-                required: false
             # Defaults to #notif-<repo-name> when empty, matching the previous behavior.
             report-slack-channel:
                 type: string
@@ -24,20 +17,16 @@ jobs:
             !contains(github.event.head_commit.message, '[skip platform-test]')
 
         runs-on: ubuntu-latest
-        defaults:
-            run:
-                working-directory: ${{ inputs.working-directory }}
-
         steps:
             - name: Setup repository and dependencies
               id: setup
               # For testing, you have to temporarily change the branch
               uses: apify/apify-test-tools/.github/actions/checkout-restore-dependencies@workflows-v0
               with:
-                  working-directory: ${{ inputs.working-directory }}
-                  additional-working-directory: ${{ inputs.additional-working-directory }}
                   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
@@ -47,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/public_review.yaml

@@ -26,13 +26,6 @@ on:
                 type: string
                 description: Model to use for Claude Code (best, sonnet, opus, haiku, sonnet[1m], opus[1m], opusplan)
                 required: false
-            working-directory:
-                type: string
-                default: .
-                required: false
-            additional-working-directory:
-                type: string
-                required: false
         secrets:
             ANTHROPIC_API_KEY:
                 required: true

package/.github/workflows-package-version

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

package/CHANGELOG.md

@@ -3,23 +3,33 @@
 All notable changes to this project will be documented in this file.
 
 <!-- git-cliff-unreleased-start -->
-## 0.9.1 - **not yet released**
+## 0.10.1 - **not yet released**
+
+### 🐛 Bug Fixes
+
+- **internal-workflows:** Wait out npm&#x27;s async publish before holding the major tag ([#160](https://github.com/apify/apify-test-tools/pull/160)) ([78434f0](https://github.com/apify/apify-test-tools/commit/78434f03d288ecbd383d55d56a1610f06ded298f)) by [@metalwarrior665](https://github.com/metalwarrior665)
+
+
+<!-- git-cliff-unreleased-end -->
+## [0.10.0](https://github.com/apify/apify-test-tools/releases/tag/v0.10.0) (2026-09-30)
 
 ### 🚀 Features
 
 - **config/modes:** Lay groundwork for multiple configuration structures ([#142](https://github.com/apify/apify-test-tools/pull/142)) ([7e18638](https://github.com/apify/apify-test-tools/commit/7e18638a8d3523154dbe819312c2b16b54c548ff)) by [@JuanGalilea](https://github.com/JuanGalilea)
 - **workflows:** Host the reusable GitHub workflows in this repo ([#120](https://github.com/apify/apify-test-tools/pull/120)) ([10f089d](https://github.com/apify/apify-test-tools/commit/10f089d85146ceb7cdae964cfa1fc2577df43a37)) by [@metalwarrior665](https://github.com/metalwarrior665)
+- **mode:** Add grouped config mode ([#143](https://github.com/apify/apify-test-tools/pull/143)) ([9d0b93e](https://github.com/apify/apify-test-tools/commit/9d0b93e194a2cd810a31bcef4ca9457fd9ebfb9b)) by [@JuanGalilea](https://github.com/JuanGalilea)
 
 ### 🐛 Bug Fixes
 
 - Apply default actor timeout to runs ([#134](https://github.com/apify/apify-test-tools/pull/134)) ([82f5f7d](https://github.com/apify/apify-test-tools/commit/82f5f7d4de990db7ad8edf940c19ffd6b20bad13)) by [@Patai5](https://github.com/Patai5)
+- Copy cli to zip to KV store local builds ([#151](https://github.com/apify/apify-test-tools/pull/151)) ([ecdda58](https://github.com/apify/apify-test-tools/commit/ecdda58b68a8c7173a023e3a92689bc4fa0ce53c)) by [@gytelio](https://github.com/gytelio), closes [#140](https://github.com/apify/apify-test-tools/issues/140)
 
 ### 🚜 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 -->
 ## [0.9.0](https://github.com/apify/apify-test-tools/releases/tag/v0.9.0) (2026-08-11)
 
 ### 🚀 Features

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,37 +12,15 @@ 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
 
-Every repo that uses `apify-test-tools` must have an `apify-test-tools.config.json` file at the root. This file tells the tool which actors live in the repo, how to identify them, and which token to use.
+Every repo that uses `apify-test-tools` must have an `apify-test-tools.config.json` file at the root. It lists the actors in the repo, their folders, their full names on the platform, and which env var holds the token to use for each. A top-level `mode` field picks the file's layout; leave it out to use the default `"legacy"` layout.
 
-```json
-{
-    "actors": [
-        {
-            "folder": "actors/web-scraper",
-            "actorFullName": "myteam/web-scraper",
-            "tokenEnvVar": "APIFY_TOKEN_MYTEAM"
-        },
-        {
-            "folder": "actors/email-sender",
-            "actorFullName": "myteam/email-sender",
-            "tokenEnvVar": "APIFY_TOKEN_MYTEAM",
-            "overrideActorContext": ["actors/email-sender", "packages/shared"]
-        }
-    ]
-}
-```
-
-Each entry has:
-
-| Field                  | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `folder`               | yes      | Relative path from repo root to the actor's own project directory — the folder that directly contains `.actor/actor.json` (i.e. `<folder>/.actor/actor.json`), the actor's README/CHANGELOG, and its source. Use `"."` for a single-actor repo where `.actor/` is at the root.                                                                                                                                                                                                                          |
-| `actorFullName`        | yes      | Full actor identifier in `owner/name` format (e.g. `"apify/web-scraper"`). This is the source of truth for the actor name — the `name` field in `actor.json` is not used.                                                                                                                                                                                                                                                                                                                               |
-| `tokenEnvVar`          | yes      | Name of the environment variable holding the Apify API token for this actor. No fallback — if the env var is not set at build time, the build fails.                                                                                                                                                                                                                                                                                                                                                    |
-| `overrideActorContext` | no       | Array of paths (relative to repo root) that define which files are relevant to this actor. When set, replaces the `dockerContextDir` from `actor.json` for change detection. Useful when an actor depends on shared packages outside its Docker build context. Entries must not be prefixes of one another (e.g. `["", "code"]` or `["actors", "actors/foo"]` are rejected). The actor's own `folder` is always part of its context — if none of the listed entries reach it, it's added automatically. |
+See [Config file](#config-file) for the available modes and every field.
 
 ### 3. Set up actor folders
 
@@ -97,6 +75,82 @@ mkdir -p test/platform/core
 
 See the [GitHub workflows](#github-worklows) section below.
 
+## Config file
+
+`apify-test-tools.config.json` lives at the repo root and tells the tool which actors live in the repo, how to identify them, and which token to use.
+
+### Actor fields
+
+Every actor in the config is described by these fields, whatever the mode:
+
+| Field                  | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `folder`               | yes      | Relative path from repo root to the actor's own project directory — the folder that directly contains `.actor/actor.json` (i.e. `<folder>/.actor/actor.json`), the actor's README/CHANGELOG, and its source. Use `"."` for a single-actor repo where `.actor/` is at the root.                                                                                                                                                                                                                          |
+| `actorFullName`        | yes      | Full actor identifier in `owner/name` format (e.g. `"apify/web-scraper"`). This is the source of truth for the actor name — the `name` field in `actor.json` is not used.                                                                                                                                                                                                                                                                                                                               |
+| `tokenEnvVar`          | yes      | Name of the environment variable holding the Apify API token for this actor. In [grouped mode](#grouped-mode) it's inherited from the group unless the actor sets its own. No fallback — if the env var is not set at build time, the build fails.                                                                                                                                                                                                                                                      |
+| `overrideActorContext` | no       | Array of paths (relative to repo root) that define which files are relevant to this actor. When set, replaces the `dockerContextDir` from `actor.json` for change detection. Useful when an actor depends on shared packages outside its Docker build context. Entries must not be prefixes of one another (e.g. `["", "code"]` or `["actors", "actors/foo"]` are rejected). The actor's own `folder` is always part of its context — if none of the listed entries reach it, it's added automatically. |
+
+### Modes
+
+The file's layout is picked by the top-level `mode` field. Each mode is a different way of writing the same thing: every mode resolves to a list of actors with the fields above, and the same rules apply to all of them — no two actors may share a `folder`, and no two entries may point at the same `actorFullName`. If `mode` is left out, [`"legacy"`](#legacy-mode) is used, so existing config files keep working unchanged.
+
+### Legacy mode
+
+The default. A flat `actors` array where every entry carries all of its settings. Good for repos with a few actors, or where every actor has different settings.
+
+```json
+{
+    "mode": "legacy",
+    "actors": [
+        {
+            "folder": "actors/web-scraper",
+            "actorFullName": "myteam/web-scraper",
+            "tokenEnvVar": "APIFY_TOKEN_MYTEAM"
+        },
+        {
+            "folder": "actors/email-sender",
+            "actorFullName": "myteam/email-sender",
+            "tokenEnvVar": "APIFY_TOKEN_MYTEAM",
+            "overrideActorContext": ["actors/email-sender", "packages/shared"]
+        }
+    ]
+}
+```
+
+`actors` must hold at least one entry. Every entry takes all the [actor fields](#actor-fields) directly, and `tokenEnvVar` is required on each one.
+
+### Grouped mode
+
+Actors are organized into `groups`, and each group sets `tokenEnvVar` and `overrideActorContext` once for all of its actors. Good for repos where many actors share the same token or context.
+
+```json
+{
+    "mode": "grouped",
+    "groups": {
+        "myteam": {
+            "tokenEnvVar": "APIFY_TOKEN_MYTEAM",
+            "overrideActorContext": ["packages/shared"],
+            "actors": [
+                { "folder": "actors/web-scraper", "actorFullName": "myteam/web-scraper" },
+                {
+                    "folder": "actors/email-sender",
+                    "actorFullName": "myteam/email-sender",
+                    "overrideActorContext": ["actors/email-sender", "packages/mailer"]
+                }
+            ]
+        },
+        "partner": {
+            "tokenEnvVar": "APIFY_TOKEN_PARTNER",
+            "actors": [{ "folder": "actors/partner-crawler", "actorFullName": "partner/crawler" }]
+        }
+    }
+}
+```
+
+`groups` is an object with at least one group. The group key (`myteam`, `partner` above) is only a label for readability; it has no effect on the result, and it does not need to match any folder or username. Each group needs a `tokenEnvVar` and at least one actor, and can optionally set `overrideActorContext`.
+
+An actor inside a group can set its own `tokenEnvVar` or `overrideActorContext`, and that value replaces the group's for that actor only. Values are replaced, not merged: in the example above, `myteam/email-sender` gets `["actors/email-sender", "packages/mailer"]`, not `packages/shared` as well.
+
 ## Github worklows
 
 The reusable workflows live in this repo, alongside the package they call. They are the
@@ -172,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
@@ -537,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
 
@@ -547,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 \
@@ -562,11 +619,10 @@ Remove `--dry-run` to actually trigger builds and update the branch names/ The c
 
 #### Build from local source (no push needed)
 
-If you don't want to push a dummy branch just to test a change and wait for all the tests to finish, `build-from-local` builds Actors directly from your local files (zipped and uploaded as `SOURCE_FILES`), skipping steps 1-4 above.
+If you don't want to push a dummy branch just to test a change and wait for all the tests to finish, `build-from-local` builds Actors directly from your local files (zipped into the Actor's `actor-<id>-source` key-value store and built as `TARBALL`, like `apify push`), skipping steps 1-4 above.
 
 ```bash
 APIFY_TOKEN_JOHN_DOE=<token> \
-GITHUB_WORKSPACE=. \
   npx apify-test-tools build-from-local --actors john.doe/my-actor
 ```
 
@@ -575,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.
@@ -598,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)
 
@@ -609,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
 ```