apify-test-tools 0.10.2-beta.3 → 0.10.2-beta.5

package/.github/scripts/run-with-apify-tokens.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Runs apify-test-tools and passes it only secrets needed for the Actors, no other secrets are leaked.
 //
-//     node .github/scripts/run-with-apify-tokens.mjs apify-test-tools build --target-branch ...
+//     jq ... | node .github/scripts/run-with-apify-tokens.mjs apify-test-tools build --version-number 0.99
 //
 // The step passes the whole secrets map as ALL_SECRETS. The token names come from `tokenEnvVar` in
 // the repo's apify-test-tools.config.json, which is the same file apify-test-tools itself reads, so

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

@@ -41,31 +41,39 @@ jobs:
                   # This is needed to force overriding the cache with new entry at the end
                   restore-keys: base_commit-
 
-            # 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
-            - name: Build
-              id: build
+            # Needs no tokens, it only reads git and apify-test-tools.config.json. The setup action checks out
+            # the PR branch itself (not GitHub's merge commit), so the range ends at the branch's HEAD.
+            - name: Find affected Actors
               env:
-                  ALL_SECRETS: ${{ toJSON(secrets) }}
                   # Branch names are attacker-controlled on fork PRs, so they reach the script as
                   # environment variables rather than being interpolated into it.
-                  HEAD_REF: ${{ github.head_ref }}
                   BASE_REF: ${{ github.base_ref }}
-                  SCRIPTS_PATH: ${{ steps.setup.outputs.scripts-path }}
               run: |
                   base_commit=$(cat base_commit.txt 2>/dev/null || echo "")
                   echo "Last validated (base) commit to be used for build & test: $base_commit"
                   args=(
-                    --source-branch "origin/$HEAD_REF"
-                    --target-branch "origin/$BASE_REF"
+                    --base "origin/$BASE_REF"
                     # TODO: Temporary hotfix until build glob matching aligns with Vitest's test selection glob.
                     --test-files-glob 'test/platform/**'
-                    --use-docker-cache
                   )
-                  [ -n "$base_commit" ] && args+=(--base-commit "$base_commit")
-                  actor_builds=$(node "$SCRIPTS_PATH/run-with-apify-tokens.mjs" \
-                    apify-test-tools build "${args[@]}")
+                  [ -n "$base_commit" ] && args+=(--since "$base_commit")
+                  apify-test-tools get-affected-actors "${args[@]}" > affected.json
+
+            # Cosmetic-only changes need no tests, so only the functionally changed Actors are built, into the
+            # test version 0.99 that users never run.
+            # 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
+            - name: Build
+              id: build
+              # bash rather than the default shell, for pipefail
+              shell: bash
+              env:
+                  ALL_SECRETS: ${{ toJSON(secrets) }}
+                  SCRIPTS_PATH: ${{ steps.setup.outputs.scripts-path }}
+              run: |
+                  actor_builds=$(jq '{ actors: .functionallyChangedActors }' affected.json \
+                    | node "$SCRIPTS_PATH/run-with-apify-tokens.mjs" apify-test-tools build --version-number 0.99)
                   echo "actor_builds=$actor_builds" | tee -a "$GITHUB_OUTPUT"
 
             # Runs the repo's test code and its whole import graph, so it gets the tester token only.
@@ -77,18 +85,10 @@ jobs:
 
             # NOTE: This is an optimization that if we did functional changes and later only cosmetic changes (e.g. dev readme), we will compare changes files only for the last commit. This must run after tests because we want to cache the latest commit only if the tests are successful
             - name: Store last validated commit to cache
-              env:
-                  HEAD_REF: ${{ github.head_ref }}
-                  BASE_REF: ${{ github.base_ref }}
               run: |
-                  base_commit=$(cat base_commit.txt 2>/dev/null || echo "")
-                  echo "Old last validated (base) commit: $base_commit"
-                  args=(
-                    --source-branch "origin/$HEAD_REF"
-                    --target-branch "origin/$BASE_REF"
-                  )
-                  [ -n "$base_commit" ] && args+=(--base-commit "$base_commit")
-                  apify-test-tools get-latest-commit "${args[@]}" > ./base_commit.txt
+                  echo "Old last validated (base) commit: $(cat base_commit.txt 2>/dev/null || echo "")"
+                  # The HEAD that was just built and tested
+                  jq -r .head affected.json > base_commit.txt
                   echo "New last validated (base) commit: $(cat base_commit.txt)"
 
     # Pure static checks against the repo. Needs no Apify or Slack credentials, only the npm

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

@@ -25,18 +25,34 @@ jobs:
               with:
                   npm-token: ${{ secrets.NPM_TOKEN }}
 
-            # --base-commit is the last commit that is already released: the push's "before" commit.
+            # --since 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.
+            # Needs no tokens, it only reads git and apify-test-tools.config.json.
+            - name: Find changes since the last release
+              run: |
+                  apify-test-tools get-affected-actors --since ${{ github.event.before }} > affected.json
+
+            # A release ships cosmetic changes too (README, input schema descriptions), so both lists are built,
+            # into each Actor's default version: the one its default build tag points to, which users run.
             # 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
-            - name: Release Actors and notify
+            - name: Build the default versions
+              # bash rather than the default shell, for pipefail
+              shell: bash
               env:
                   ALL_SECRETS: ${{ toJSON(secrets) }}
+              run: |
+                  jq '{ actors: (.functionallyChangedActors + .cosmeticallyChangedActors) }' affected.json \
+                    | node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
+                        apify-test-tools build --version-number default
+
+            # Skips the announcement when the push brought no new commits
+            - name: Announce the release on Slack
+              env:
                   SLACK_TOKEN_RELEASES_BOT: ${{ secrets.SLACK_TOKEN_RELEASES_BOT }}
               run: |
-                  node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
-                    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
+                  apify-test-tools notify-release --release-slack-channel "#delivery-public-actors" --report-slack-channel "${{ inputs.report-slack-channel || format('#notif-{0}', github.event.repository.name) }}" < affected.json
 
             - name: Delete old builds
               env:

package/CHANGELOG.md

@@ -9,12 +9,18 @@ All notable changes to this project will be documented in this file.
 
 - **ci:** Ship the workflows' CLI as a bundle in the action instead of installing it ([#200](https://github.com/apify/apify-test-tools/pull/200)) ([a0ef975](https://github.com/apify/apify-test-tools/commit/a0ef9756123a30a8210590b080a2a289c6a9c17c)) by [@metalwarrior665](https://github.com/metalwarrior665)
 - [**breaking**] Revamp get-affected-actors to be a core logic command ([#190](https://github.com/apify/apify-test-tools/pull/190)) ([ea5f244](https://github.com/apify/apify-test-tools/commit/ea5f244cfd42bf3fa9ffd38cd2ad499dde2e83f8)) by [@metalwarrior665](https://github.com/metalwarrior665)
+- [**breaking**] Add logic-less build command and use command chaining in workflows ([#193](https://github.com/apify/apify-test-tools/pull/193)) ([e5b0b86](https://github.com/apify/apify-test-tools/commit/e5b0b86ee06fca51d4be0ddc81b0a4a469d31603)) by [@metalwarrior665](https://github.com/metalwarrior665)
+- **get-affected-actors:** Three-dot diff, narrowed per Actor with --since ([#204](https://github.com/apify/apify-test-tools/pull/204)) ([fa9a0e7](https://github.com/apify/apify-test-tools/commit/fa9a0e7518764dd4722ec9ecbf67b2a26a5a062e)) by [@metalwarrior665](https://github.com/metalwarrior665)
 
 ### 🐛 Bug Fixes
 
 - **toBeObject:** Reject null ([#191](https://github.com/apify/apify-test-tools/pull/191)) ([6bdae49](https://github.com/apify/apify-test-tools/commit/6bdae4905756e0ae8dd6146942e6fc04dbead48e)) by [@JuanGalilea](https://github.com/JuanGalilea), closes [#88](https://github.com/apify/apify-test-tools/issues/88)
 - Build and test on test-only changes even when .dockerignore lists the tests ([#177](https://github.com/apify/apify-test-tools/pull/177)) ([5cb1b5a](https://github.com/apify/apify-test-tools/commit/5cb1b5ab5f6f43ec279f9624b402e73d55a5974a)) by [@artogahr](https://github.com/artogahr), closes [#145](https://github.com/apify/apify-test-tools/issues/145)
 
+### 🚜 Refactor
+
+- [**breaking**] Remove build-for-test and release composite commands ([#203](https://github.com/apify/apify-test-tools/pull/203)) ([85efc54](https://github.com/apify/apify-test-tools/commit/85efc54697e98208c827c4f450906e00eebcd9ca)) by [@metalwarrior665](https://github.com/metalwarrior665)
+
 
 <!-- git-cliff-unreleased-end -->
 ## [0.10.1](https://github.com/apify/apify-test-tools/releases/tag/v0.10.1) (2026-10-13)

package/CONTRIBUTING.md

@@ -94,9 +94,12 @@ npm release relate — the short version:
 - the CLI runs from `.github/cli/apify-test-tools.mjs`, a bundle the pre-commit hook rebuilds with
   `npm run bundle`. If you commit with `--no-verify`, run it yourself: the `CLI bundle` check fails
   on a stale bundle, and a stale bundle would hold the tag.
-- `npm test` covers the bundle without network (`test/bundle/`). `npm run test:e2e` runs it against two
+- `npm test` covers the bundle without network (`test/bundle/`). `npm run test:e2e` runs it against
   dummy Actors in an isolated sandbox account (`test/e2e/`) and skips itself unless
   `E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR` is set. CI passes that secret only to the `E2E tests` job.
+  The git `build` and release pipeline tests clone
+  [testing-repo-for-github-actions](https://github.com/apify-store/testing-repo-for-github-actions) and
+  use its `e2e/base` and `e2e/feature` branches as fixtures, so never rebase or delete those.
 
 `npm run lint` and `actionlint` (via the `Code checks` workflow) both gate master, so run them before
 pushing workflow changes.

package/README.md

@@ -57,7 +57,7 @@ When a PR is opened or code is pushed, the tool determines which actors need to
 2. **CHANGELOG classification** — a `CHANGELOG.md` file is always `cosmetic` (only triggers a release build, not tests), for every actor, regardless of context or folder. (See [issue #106](https://github.com/apify/apify-test-tools/issues/106).)
 3. **Context matching** — the file must fall within one of the actor's context paths (`dockerContextDir` from `actor.json` by default, or `overrideActorContext` from config if set). Files outside every context path are skipped.
 4. **Hardcoded ignore list, context-aware** — the file path is first "hoisted" relative to the context path it matched (e.g. a standalone actor's own `.eslintrc` is checked as just `.eslintrc`, not the full repo-root-relative path), then checked against repo-level dev file patterns (`.vscode/`, `.gitignore`, `.husky/`, `.eslintrc`, `eslint.config.mjs`, `.prettierrc`, `.editorconfig`). There's no hardcoded special-casing for legacy `code/`/`shared/` layouts — repos that need those directories treated as top-level must list them explicitly in `overrideActorContext`.
-5. **`.dockerignore` filtering** — if a `.dockerignore` exists at the root of the actor's `dockerContextDir`, matching files are ignored. Patterns are resolved relative to `dockerContextDir`, matching Docker's own behavior. Test files are the exception: `build --test-files-glob <glob>` (relative to the repo root) skips this check for matching files, so a changed test triggers a build, and with it its tests, even when `.dockerignore` lists it. The PR workflow passes `test/platform/**`. Context matching still applies, so tests outside an actor's `dockerContextDir` (e.g. a root `test/` with standalone actors) need to be listed in its `overrideActorContext`; `build` logs a warning for changed test files outside every actor's context.
+5. **`.dockerignore` filtering** — if a `.dockerignore` exists at the root of the actor's `dockerContextDir`, matching files are ignored. Patterns are resolved relative to `dockerContextDir`, matching Docker's own behavior. Test files are the exception: `get-affected-actors --test-files-glob <glob>` (relative to the repo root) skips this check for matching files, so a changed test triggers a build, and with it its tests, even when `.dockerignore` lists it. The PR workflow passes `test/platform/**`. Context matching still applies, so tests outside an actor's `dockerContextDir` (e.g. a root `test/` with standalone actors) need to be listed in its `overrideActorContext`; `get-affected-actors` logs a warning for changed test files outside every actor's context.
 6. **README classification** — a `README.md` file is `cosmetic` (only triggers a release build, not tests) if it lives inside the actor's own `folder`; otherwise it's ignored entirely, since it isn't documentation for this actor.
 7. **Cosmetic JSON classification** — `.json` files inside the actor's own `.actor/` directory with only cosmetic schema changes (whitespace, key ordering) only trigger a release build.
 8. **Functional** — everything else triggers both build and tests.
@@ -226,9 +226,9 @@ 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.
+This workflow runs one step per command: `get-affected-actors --since ${{ github.event.before }}`, then
+`build --version-number default` on every changed Actor, then `notify-release`. See [Releasing Actors](#releasing-actors) for how the
+released range is determined and what to pass if you call the CLI from somewhere else.
 
 ### `claude-review.yaml`
 
@@ -261,9 +261,9 @@ environment variables, so a secret is only visible to the step that needs it:
 | Secret                                                                    | Reaches                                                                                                                                                                                                                      |
 | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `NPM_TOKEN`                                                               | dependency install steps only, as both `NPM_TOKEN` and `NODE_AUTH_TOKEN`. Use a read-only token: npm granular tokens can be read-only, classic automation tokens can publish.                                                |
-| the Actor tokens named by `tokenEnvVar` in `apify-test-tools.config.json` | the `build`, `release`, and `delete-old-builds` steps only                                                                                                                                                                   |
+| the Actor tokens named by `tokenEnvVar` in `apify-test-tools.config.json` | the build and `delete-old-builds` steps only                                                                                                                                                                                 |
 | `TESTER_APIFY_TOKEN`                                                      | the vitest step, and the Claude investigation step: the Apify MCP server's bearer token for reading the failing run, its log and its storages, and Claude's token for re-running it to measure how often the failure happens |
-| `SLACK_TOKEN_TESTS_BOT` / `SLACK_TOKEN_RELEASES_BOT`                      | the reporting and release steps only                                                                                                                                                                                         |
+| `SLACK_TOKEN_TESTS_BOT` / `SLACK_TOKEN_RELEASES_BOT`                      | the reporting and announcement steps only                                                                                                                                                                                    |
 
 The Actor tokens are the one set that cannot be listed in the workflow, because each Actor names its
 own token via `tokenEnvVar` in `apify-test-tools.config.json`. Those steps pass
@@ -273,11 +273,13 @@ secrets to pass on:
 
 ```yaml
 - name: Build
+  shell: bash
   env:
       ALL_SECRETS: ${{ toJSON(secrets) }}
   run: |
-      node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
-        npx apify-test-tools build --target-branch ...
+      jq '{ actors: .functionallyChangedActors }' affected.json \
+        | node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
+          npx apify-test-tools build --version-number 0.99
 ```
 
 The wrapper passes only the tokens the config declares and drops `ALL_SECRETS`, so neither `npx` nor
@@ -568,7 +570,7 @@ The package includes a CLI binary used by CI workflows to build Actors, detect c
 
 ### Dry runs (`--dry-run`)
 
-Every command that changes something (`build`, `build-from-local`, `release`, `delete-old-builds`, `report-tests`) takes `--dry-run`. A dry run:
+Every command that changes something (`build`, `build-from-local`, `notify-release`, `delete-old-builds`, `report-tests`) takes `--dry-run`. A dry run:
 
 - **Changes nothing.** No versions or builds are created, nothing is uploaded or deleted, and no Slack message is posted.
 - **Does every read and check the real run does**, so it fails wherever the real run would: change detection, the Apify token and Actor lookup, the [repository check](#repository-check), collecting and zipping local sources, and the Slack token (verified with Slack's read-only `auth.test`).
@@ -598,14 +600,15 @@ If you want to test vs existing src code, you can skip this and instead construc
 Requires `APIFY_TOKEN_<USERNAME>` for all Apify users that own your Actors (e.g. `apify`, `compass`, `lukaskrivka` users). The username is derived from the actor name — uppercased with non-word chars replaced by `_` (e.g. Actor `john.doe/my-actor` needs `APIFY_TOKEN_JOHN_DOE`).
 
 ```bash
-APIFY_TOKEN_JOHN_DOE=<token> \
-  npx apify-test-tools build \
-    --target-branch origin/master \
-    --source-branch origin/my-dummy-branch \
-    --dry-run
+npx apify-test-tools get-affected-actors --base origin/master \
+  | jq '{ actors: .functionallyChangedActors }' \
+  | APIFY_TOKEN_JOHN_DOE=<token> npx apify-test-tools build --version-number 0.99 --dry-run
 ```
 
-With `--dry-run`, it prints the plan (the version and Git URL each Actor would be built from). Remove `--dry-run` to actually trigger builds and update the branch names. The command outputs a JSON array of build objects to stdout:
+Run it with your dummy branch checked out: it builds the Actors that branch changed functionally, from the branch
+as it is on the remote, into the test version `0.99`. With `--dry-run`, it prints the plan (the version and Git URL
+each Actor would be built from). Remove `--dry-run` to actually trigger builds, and update `--base` to the branch
+you compare against. `build` outputs a JSON array of build objects to stdout:
 
 ```json
 [{ "buildId": "...", "actorRawId": "...", "buildNumber": "...", "actorFullName": "john.doe/my-actor" }]
@@ -644,15 +647,13 @@ TESTER_APIFY_TOKEN=<token> \
 
 #### Full example
 
-Tests only run for Actors in `ACTOR_BUILDS`, so a custom workflow has to build (and pass) the Actors even when only tests changed. Pass `--test-files-glob` so test changes count even when `.dockerignore` lists them.
+Tests only run for Actors in `ACTOR_BUILDS`, so a custom workflow has to build (and pass) the Actors even when only tests changed. Pass `--test-files-glob` to `get-affected-actors` so test changes count even when `.dockerignore` lists them.
 
 ```bash
 # Build and capture output
-BUILDS=$(APIFY_TOKEN_JOHN_DOE=apify_api_xxx \
-    npx apify-test-tools build \
-    --target-branch origin/master \
-    --source-branch origin/my-dummy-branch \
-    --test-files-glob 'test/platform/**')
+BUILDS=$(npx apify-test-tools get-affected-actors --base origin/master --test-files-glob 'test/platform/**' \
+    | jq '{ actors: .functionallyChangedActors }' \
+    | APIFY_TOKEN_JOHN_DOE=apify_api_xxx npx apify-test-tools build --version-number 0.99)
 
 # Run tests with the builds
 ACTOR_BUILDS="$BUILDS" \
@@ -667,7 +668,7 @@ TESTER_APIFY_TOKEN=apify_api_yyy \
 The range always ends at the checked-out `HEAD`, so check out the branch you want to inspect first.
 
 ```bash
-# A PR: the branch's own commits, after its last validated commit
+# A PR: the branch's own changes, narrowed to the Actors that changed since its last validated commit
 npx apify-test-tools get-affected-actors --base origin/master --since <sha>
 
 # A release: everything after the last released commit
@@ -676,29 +677,36 @@ npx apify-test-tools get-affected-actors --since <sha>
 
 | Flag                | Default | Meaning                                                                                                                                    |
 | ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `--base`            |         | Only commits on `HEAD` that are not on this branch count                                                                                   |
-| `--since`           |         | Only commits after this one count (see below)                                                                                              |
+| `--base`            |         | Only what `HEAD` changes compared to this branch counts, like `git diff <base>...HEAD`                                                     |
+| `--since`           |         | Only changes after this commit count (see below)                                                                                           |
 | `--test-files-glob` |         | Test files (glob from the repo root) that count as changes even when `.dockerignore` lists them, see [Change detection](#change-detection) |
 | `--actors`          | all     | Only report these Actors                                                                                                                   |
 | `--ignore`          | none    | Never report these Actors                                                                                                                  |
 
 Pass `--base`, `--since`, or both:
 
-- **`--base` only** inspects the whole branch. If the branch merged `--base` in and has no functional changes
-  of its own, no Actor is reported as functional, since `--base` is already validated (and none as cosmetic
-  either, if the branch has no changes of its own at all).
-- **`--base` and `--since`** inspects the branch after its last validated commit. If `--since` is not on the
-  branch (force-push), or it is the head (a rerun), the whole branch is inspected instead.
+- **`--base` only** inspects what the branch changes, the same files GitHub's "Files changed" tab shows: the diff
+  from where the branch forked from `--base`, or the last commit of `--base` it merged in. What it merged in from
+  `--base` is already validated there, so it doesn't count.
+- **`--base` and `--since`** also inspects what changed after the branch's last validated commit, and reports only
+  the Actors that changed in both. An Actor in only one of them is already validated, by this branch or on `--base`.
+  When both changed an Actor, the changes can interact, so it is reported, but as functional only when both changes
+  are functional. A validated functional change followed by README edits is cosmetic, and so is a functional
+  change merged in from `--base` that meets only cosmetic changes of the branch. `--since` doesn't have to be on
+  the branch, so a rebase only re-checks the Actors that `--base` changed too. If `--since` is not in the local
+  history (a force-push), or it is `HEAD` (a rerun), it is ignored and the whole branch is checked.
 - **`--since` only** inspects everything after it up to `HEAD`. It must be an ancestor of `HEAD` and fails
-  otherwise, exactly like [`--base-commit` of `release`](#--base-commit). If `HEAD` is `--since`, nothing is
+  otherwise, see [Releasing Actors](#releasing-actors). If `HEAD` is `--since`, nothing is
   reported.
 
+`commits`, `changedFiles` and `changelog` describe the whole range, `--base...HEAD` or `--since..HEAD`: `--since`
+together with `--base` only narrows the Actor lists.
+
 The output is a JSON document:
 
 ```json
 {
     "version": 1,
-    "ref": "my-branch",
     "head": "<sha of HEAD>",
     "commits": [{ "sha": "…", "author": "…", "date": "…", "message": "…" }],
     "changedFiles": ["src/main.ts", "CHANGELOG.md"],
@@ -710,30 +718,71 @@ The output is a JSON document:
 
 Each changed Actor is in exactly one of the lists. `functionallyChangedActors` have at least one functional change, so
 they need a new build and tests. `cosmeticallyChangedActors` only have cosmetic changes (see
-[Change detection](#change-detection)), so they need a new build only when released: `build` builds
-`functionallyChangedActors`, `release` builds both.
+[Change detection](#change-detection)), so they need a new build only when released: the PR workflow builds
+`functionallyChangedActors`, the release workflow builds both.
+
+### Building Actors (`build`)
 
-`ref` is the checked-out branch, or `null` for a detached HEAD. `build` and `release` use the same detection internally.
+`build` builds exactly the Actors it is given on stdin, from the checked-out branch as it is on the remote, and
+prints the builds as the same JSON array `build-from-local` prints. A detached HEAD is an
+error, since there is no branch to build from. It doesn't look at git history: which Actors to build is
+up to you, usually picked from the output of [`get-affected-actors`](#finding-affected-actors-get-affected-actors).
 
-### Releasing Actors (`release`)
+```bash
+# A PR: the Actors a branch changed functionally, built into the test version
+npx apify-test-tools get-affected-actors --base origin/master \
+  | jq '{ actors: .functionallyChangedActors }' \
+  | npx apify-test-tools build --version-number 0.99
+
+# A release: every Actor changed since the last release, into the version users run
+npx apify-test-tools get-affected-actors --since <sha> \
+  | jq '{ actors: (.functionallyChangedActors + .cosmeticallyChangedActors) }' \
+  | npx apify-test-tools build --version-number default
+
+# One Actor, whatever changed
+echo '{ "actors": [{ "actorFullName": "john.doe/my-actor" }] }' | npx apify-test-tools build --version-number 0.99
+```
 
-`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.
+The input is `{ "actors": [{ "actorFullName": "<owner/name>" }] }`; other fields are ignored. An empty `actors` list builds nothing and prints `[]`. Empty or invalid input is an error,
+so a failed command earlier in the pipe can't turn into a successful run that built nothing. In GitHub
+Actions, give such a step `shell: bash` so the pipe also fails on its own (the default shell has no `pipefail`).
+
+| Flag               | Default             | Meaning                                                                                                                |
+| ------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `--version-number` | required            | Version to build, like `0.99`, or `default` for each Actor's default version (the one its default build tag points to) |
+| `--repo-url`       | the `origin` remote | Repository to build from, see [Repository check](#repository-check)                                                    |
+
+`build` never sets or changes build tags. A build gets the tag its version is configured with on the platform,
+so building the default version moves its tag (usually `latest`) to the new build, and building a version
+without a tag leaves every tag where it is. Builds always use the Docker cache.
+
+### Releasing Actors
+
+A release is three commands: find what changed since the last released commit, build those Actors into
+their default version (the one users run), and announce it.
 
 ```bash
-npx apify-test-tools release --base-commit <sha> --release-slack-channel "#releases" --dry-run
+npx apify-test-tools get-affected-actors --since <sha> > affected.json
+
+jq '{ actors: (.functionallyChangedActors + .cosmeticallyChangedActors) }' affected.json \
+  | npx apify-test-tools build --version-number default --dry-run
+
+npx apify-test-tools notify-release --release-slack-channel "#releases" --dry-run < affected.json
 ```
 
-#### `--base-commit`
+`notify-release` reads the output of `get-affected-actors` on stdin. It posts the changelog additions to
+`--release-slack-channel` and the commits and changed files to `--report-slack-channel`, and posts nothing when
+there are no new commits. It names the release after the `origin` remote (or `--repo-url`) and the author of the
+newest commit, and needs `SLACK_TOKEN_RELEASES_BOT`.
+
+#### The last released commit (`--since`)
 
-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 last commit that is **already released**. Everything after it, up to `HEAD`, is released. Git alone
+can't tell which commits a push brought, and guessing wrong silently leaves Actors on old code, so it has
+to be passed.
 
-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:
+The changed files come from diffing `--since` and `HEAD` directly, so this works for every merge strategy as
+long as `--since` is the branch tip from **before** the push:
 
 | Merge strategy                 | What lands on the branch          | What to pass                                                           |
 | ------------------------------ | --------------------------------- | ---------------------------------------------------------------------- |
@@ -743,26 +792,25 @@ merge strategy as long as the base commit is the branch tip from **before** the
 
 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.
+needs the full history (`fetch-depth: 0` in `actions/checkout`) so the commit is available locally.
 
-`release` fails instead of guessing when:
+`get-affected-actors --since` without `--base` 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 commit is all zeros (GitHub sends this for a push that created the branch)
+- the 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.
+In those cases, rerun it with a `--since` 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 are reported; it never forces a build, so on its own it doesn't get past these errors.
+If `HEAD` is `--since`, nothing is reported, so nothing is built or announced.
 
 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
+`build` points 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