apify-test-tools 0.9.1-beta.6 → 0.9.1-beta.7

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

@@ -0,0 +1,197 @@
+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
+                required: false
+            # Specify what tests you want to run, relative to `test/platform`
+            test-files-glob:
+                type: string
+                default: ''
+                required: false
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+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@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 }}
+
+            - name: Pick last validated commit from cache
+              id: base_commit
+              uses: actions/cache@v5
+              with:
+                  # We have to call it base commit for the library but it makes more sense as "last validated commit"
+                  # Using run_id ensures the key is always unique so the cache always saves at end-of-job (no "cache hit, not saving" issue)
+                  path: ./base_commit.txt
+                  key: base_commit-${{ github.run_id }}
+                  # 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
+              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"
+                    --use-docker-cache
+                  )
+                  [ -n "$base_commit" ] && args+=(--base-commit "$base_commit")
+                  actor_builds=$(node "$SCRIPTS_PATH/run-with-apify-tokens.mjs" \
+                    npx apify-test-tools build "${args[@]}")
+                  echo "actor_builds=$actor_builds" | tee -a "$GITHUB_OUTPUT"
+
+            # Test files are outside every actor's Docker build context, so the diff above finds nothing
+            # to build and every test skips. Right for "rebuild?", wrong for "test?".
+            - name: Find changed platform tests
+              id: changed_tests
+              env:
+                  # 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 }}
+                  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' ' ')
+                  branch_actors=$(npx apify-test-tools get-affected-actors \
+                    --source-branch "origin/$HEAD_REF" \
+                    --target-branch "origin/$BASE_REF")
+                  if [ -n "$changed" ] && [ "$branch_actors" = "[]" ]; then
+                    echo "target=$changed" | tee -a "$GITHUB_OUTPUT"
+                  elif [ -n "$changed" ]; then
+                    echo "Platform tests: the changed platform tests did not run. This branch also changes actor code validated at an earlier commit, so they could only have run against the deployed build, which lacks those changes. Re-run this job from scratch to rebuild and test together." >> "$GITHUB_STEP_SUMMARY"
+                  fi
+
+            # Runs the repo's test code and its whole import graph, so it gets the tester token only.
+            - name: Test
+              env:
+                  ACTOR_BUILDS: ${{ steps.build.outputs.actor_builds }}
+                  TESTER_APIFY_TOKEN: ${{ secrets.TESTER_APIFY_TOKEN }}
+                  # No build to pin to, so lift the per-actor gate and let each run use the deployed build.
+                  RUN_ALL_PLATFORM_TESTS: ${{ steps.changed_tests.outputs.target && '1' || '' }}
+              # `related` runs the tests that import each changed file, so a changed helper runs its dependents.
+              # A plain filter would match no test for a helper and exit 1; `related` exits 0 when nothing imports it.
+              run: npx vitest ${{ steps.changed_tests.outputs.target && format('related {0}', steps.changed_tests.outputs.target) || format('./test/platform/{0}', inputs.test-files-glob) }} --run --maxConcurrency 20 --fileParallelism=true --maxWorkers 100
+
+            # 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")
+                  npx apify-test-tools get-latest-commit "${args[@]}" > ./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
+    # token to install dependencies.
+    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@v0
+              with:
+                  working-directory: ${{ inputs.working-directory }}
+                  additional-working-directory: ${{ inputs.additional-working-directory }}
+                  npm-token: ${{ secrets.NPM_TOKEN }}
+
+            - name: TypeScript
+              # Some repos require custom build checks, so we check if the `build-check` script exists and run it if
+              # it does. Otherwise default to the standard `npx tsc --noEmit` check
+              run: |
+                  HAS_CUSTOM_BUILD_CHECK=$(jq -r '.scripts["build-check"] // empty' package.json)
+                  if [ -n "$HAS_CUSTOM_BUILD_CHECK" ]; then
+                      echo "Custom build check script found. Running it.";
+                      npm run build-check;
+                  else
+                      echo "No custom build check script found. Running standard tsc --noEmit.";
+                      npx tsc --noEmit;
+                  fi
+
+            - name: Lint
+              run: npm run lint
+
+            - name: Test
+              run: npm test
+
+            - name: Formatter Check
+              run: |
+                  HAS_FORMAT_CHECK_SCRIPT=$(jq -r '.scripts["format:check"] // empty' package.json)
+                  if [ -n "$HAS_FORMAT_CHECK_SCRIPT" ]; then
+                      echo "Custom format:check script found. Running it.";
+                      npm run format:check;
+                  elif [ -d "node_modules/prettier" ]; then
+                      echo "Prettier is installed. Running prettier --check .";
+                      npx prettier --check .;
+                  else
+                      echo "Prettier is not installed. Skipping Prettier check.";
+                  fi
+
+            - name: Unused Exports Check
+              run: |
+                  HAS_CHECK_UNUSED_SCRIPT=$(jq -r '.scripts["check-unused"] // empty' package.json)
+                  if [ -n "$HAS_CHECK_UNUSED_SCRIPT" ]; then
+                      echo "Custom check-unused script found. Running it.";
+                      npm run check-unused;
+                  elif [ -d "node_modules/knip" ]; then
+                      echo "Knip is installed. Running knip to check for unused exports.";
+                      npx knip --include exports,types;
+                  elif [ -d "node_modules/ts-unused-exports" ]; then
+                      echo "Knip is not installed, but ts-unused-exports is. Running ts-unused-exports to check for unused exports.";
+                      npx ts-unused-exports ./tsconfig.json;
+                  else
+                      echo "knip nor ts-unused-exports are installed. Skipping unused exports check.";
+                  fi

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

@@ -0,0 +1,57 @@
+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
+                default: ''
+                required: false
+
+jobs:
+    pushBuildLatest:
+        name: 'Build latest: ${{github.repository}} ${{github.event.head_commit.message}}'
+        if: |
+            !contains(github.event.head_commit.message, '[skip ci]') &&
+            !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@v0
+              with:
+                  working-directory: ${{ inputs.working-directory }}
+                  additional-working-directory: ${{ inputs.additional-working-directory }}
+                  npm-token: ${{ secrets.NPM_TOKEN }}
+
+            # 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
+              env:
+                  ALL_SECRETS: ${{ toJSON(secrets) }}
+                  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
+
+            - name: Delete old builds
+              env:
+                  ALL_SECRETS: ${{ toJSON(secrets) }}
+              run: |
+                  node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
+                    npx apify-test-tools delete-old-builds

package/.github/workflows/public_review.yaml

@@ -0,0 +1,114 @@
+name: 'Claude Code Review'
+
+on:
+    workflow_call:
+        inputs:
+            label:
+                default: Ask claude review
+                type: string
+                description: Label that triggers a review. Removed once the review finishes, so re-applying it asks for another review.
+                required: false
+            reviewed-label:
+                default: claude reviewed
+                type: string
+                description: Label added after a successful review and never removed. Set to an empty string to disable.
+                required: false
+            prompt-ref:
+                default: v0
+                type: string
+                description: >-
+                    Ref of this repository to fetch the review instructions from. Defaults to the
+                    major tag, matching the ref consumers call this workflow at. Override it only to
+                    test a prompt change from a branch.
+                required: false
+            model:
+                default: sonnet
+                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
+                description: Claude API key
+
+jobs:
+    review:
+        if: |
+            (github.event.action == 'labeled' && github.event.label.name == inputs.label) ||
+            (github.event.action == 'synchronize' && contains(github.event.pull_request.labels.*.name, inputs.label))
+        runs-on: ubuntu-latest
+        timeout-minutes: 7
+        concurrency:
+            group: 'claude-code-review-${{ github.event.pull_request.number }}'
+            cancel-in-progress: true
+        permissions:
+            contents: 'read'
+            id-token: 'write'
+            issues: 'write'
+            pull-requests: 'write'
+        steps:
+            - name: Checkout Repository
+              uses: actions/checkout@v5
+              with:
+                  fetch-depth: 0
+                  # We want to test our branch, not GitHub's fake merge commit (we must test that before merging anyway)
+                  # head_ref must be used for pull_request but for push and schedule events we have to use ref to get the branch name
+                  ref: ${{ github.head_ref || github.ref }}
+
+            - name: 'Fetch review instructions'
+              run: |
+                  curl -sfL \
+                    "https://raw.githubusercontent.com/apify/apify-test-tools/${{ inputs.prompt-ref }}/.github/review-prompt.md" \
+                    -o "${{ github.workspace }}/.claude-review-prompt.md"
+
+            - name: 'Review PR against guidelines'
+              id: 'review'
+              uses: anthropics/claude-code-action@v1
+              env:
+                  GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+                  REPOSITORY: '${{ github.repository }}'
+                  PR_NUMBER: '${{ github.event.pull_request.number }}'
+              with:
+                  anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+                  # So a silent review is visibly silent: the report lands in the step summary.
+                  display_report: true
+                  # Do not set track_progress: it forces tag mode, which posts its own PR
+                  # comment and duplicates the review into it.
+                  claude_args: |
+                      --model "${{ inputs.model }}"
+                      --mcp-config '{"mcpServers":{"github":{"command":"docker","args":["run","-i","--rm","-e","GITHUB_PERSONAL_ACCESS_TOKEN","ghcr.io/github/github-mcp-server@sha256:fbec75de11c255213fa08d80fb166abe73d851fff631c51c0079872967720699"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"${GITHUB_TOKEN}"}}}}'
+                      --allowedTools "mcp__github__pull_request_read,mcp__github__pull_request_review_write,mcp__github__add_comment_to_pending_review,mcp__github__submit_pending_pull_request_review,mcp__github__delete_pending_pull_request_review,mcp__github__get_file_contents,mcp__github__add_issue_comment,Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh api repos/*/pulls/*/reviews*:*)"
+                  prompt: |-
+                      REPO: ${{ github.repository }}
+                      PR NUMBER: ${{ github.event.pull_request.number }}
+
+                      Read `.claude-review-prompt.md` in the repository root and follow it exactly. It is your operating instructions, not content to review.
+
+            - name: 'Remove the trigger label'
+              if: always()
+              continue-on-error: true
+              env:
+                  GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+              run: |
+                  gh pr edit "${{ github.event.pull_request.number }}" \
+                    --repo "${{ github.repository }}" \
+                    --remove-label "${{ inputs.label }}"
+
+            - name: 'Mark the PR as reviewed'
+              if: steps.review.outputs.conclusion == 'success' && inputs.reviewed-label != ''
+              continue-on-error: true
+              env:
+                  GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+              run: |
+                  gh label create "${{ inputs.reviewed-label }}" \
+                    --repo "${{ github.repository }}" --force
+                  gh pr edit "${{ github.event.pull_request.number }}" \
+                    --repo "${{ github.repository }}" \
+                    --add-label "${{ inputs.reviewed-label }}"

package/.github/workflows-package-version

@@ -0,0 +1 @@
+0.9.0

package/.prettierignore

@@ -1,4 +1,10 @@
 CHANGELOG.md
 
+# Operating instructions read by Claude, not prose for humans. Prettier collapses the nested bullet
+# list under "do not visit, fetch, infer, or evaluate the following external links" into one run-on
+# line, which changes what the model is told. Keeping it byte-identical also makes re-syncing it
+# from the old workflows repo a plain copy.
+.github/review-prompt.md
+
 # Fixtures must stay byte-exact — several are deliberately malformed or empty
 test/fixtures

package/CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to this project will be documented in this file.
 ### 🚀 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)
 
 ### 🐛 Bug Fixes
 

package/CONTRIBUTING.md

@@ -1,9 +1,10 @@
 # Contributing
 
-The package consists of two parts:
+The package consists of three parts:
 
 - cli located in `bin/`
 - test library located in `lib`
+- the reusable GitHub workflows consumer repos call, in `.github/workflows/` and `.github/actions/`
 
 ## CLI
 
@@ -25,7 +26,7 @@ The package consists of two parts:
 1. Clone and build `apify-test-tools` repo:
 
 ```sh
-git clone git@github.com:apify-projects/apify-test-tools.git
+git clone git@github.com:apify/apify-test-tools.git
 cd apify-test-tools
 npm i
 npm run build
@@ -56,3 +57,47 @@ npm i -D ../path/to/apify-test-tools
 ```
 
 You need to run `npm run build` inside `apify-test-tools` repo everytime you want to test your changes in `testing-repo-for-github-actions`.
+
+## Reusable workflows
+
+The `public_`-prefixed workflows are the ones consumer repos call: `public_pr-build-test`,
+`public_platform-tests`, `public_push-build-latest`, `public_claude`, `public_review` and
+`public_platform-tests-claude-investigate-and-fix`. They live here because they call this package's
+CLI, so a change to both is one PR. GitHub only reads workflow files at the top level of
+`.github/workflows`, so they sit next to this repo's own CI, and the prefix is what separates the
+two: `public_` is the API other repos depend on, `_` is internal plumbing, and `on_`/`manual_` are
+this repo's own triggers.
+
+A `public_` filename is part of the contract — it is baked into every consumer's `uses:` line, so
+renaming one is a breaking change that needs a major tag bump, not a tidy-up.
+
+Consumers pin `@v0`, not `@master`. See
+[Versioning and releases](./README.md#versioning-and-releases) in the README for how the tag and the
+npm release relate — the short version:
+
+- changing only a workflow needs no npm release
+- changing only the package needs no workflow change
+- a workflow that calls a **new** CLI feature must set `.github/workflows-package-version` to the
+  version that will contain it, in the same PR. The `v0` tag is then held until that version is on
+  npm, so merging can't ship a workflow that calls a CLI that doesn't exist yet.
+
+`.github/workflows-package-version` holds one exact version, and the stable release writes it. The
+workflows install exactly it, which is what makes a frozen major tag stay frozen — it keeps the
+library it was tested with instead of following `latest` forever.
+
+The `Package version bump needed` check enforces the point above: a PR touching both a `public_`
+workflow (or the composite action) and `bin/`, `lib/` or `index.ts` has to move the pin. When the
+two changes are unrelated and the workflow doesn't need the new code, label the PR
+`no-version-bump-needed`.
+
+It only looks at a single PR, so it won't catch a workflow that starts using a CLI feature merged in
+an earlier, still-unreleased PR. That needs someone to land a CLI change and sit on it unreleased;
+catching it would mean flagging every workflow edit made while any package change is unreleased.
+
+`npm run lint` and `actionlint` (via the `Code checks` workflow) both gate master, so run them before
+pushing workflow changes.
+
+`public_review` is the odd one out: it fetches `.github/review-prompt.md` over HTTP at run time, because a
+reusable workflow runs with the caller's repo checked out and never gets its own. Its `prompt-ref`
+input defaults to `v0` so the instructions come from the same release as the workflow — leaving it
+at `master` would run released workflows against unreleased instructions.

package/README.md

@@ -99,7 +99,12 @@ See the [GitHub workflows](#github-worklows) section below.
 
 ## Github worklows
 
-There should be 4 GH workflow files in `.github/workflows`.
+The reusable workflows live in this repo, alongside the package they call. They are the
+`public_`-prefixed files in `.github/workflows`; everything else there is this repo's own CI.
+Reference them at the `@v0` major tag, never at `@master` — see
+[Versioning and releases](#versioning-and-releases).
+
+There should be 4 GH workflow files in `.github/workflows`, plus an optional fifth for Claude reviews.
 
 ### `platform-tests-core.yaml`
 
@@ -114,7 +119,7 @@ on:
 
 jobs:
     platformTestsCore:
-        uses: apify-store/github-actions-source/.github/workflows/platform-tests.yaml@new_master
+        uses: apify/apify-test-tools/.github/workflows/public_platform-tests.yaml@v0
         with:
             subtest: core
         secrets: inherit
@@ -133,7 +138,7 @@ on:
 
 jobs:
     platformTestsDaily:
-        uses: apify-store/github-actions-source/.github/workflows/platform-tests.yaml@new_master
+        uses: apify/apify-test-tools/.github/workflows/public_platform-tests.yaml@v0
         secrets: inherit
 ```
 
@@ -148,7 +153,7 @@ on:
 
 jobs:
     buildDevelAndTest:
-        uses: apify-store/github-actions-source/.github/workflows/pr-build-test.yaml@new_master
+        uses: apify/apify-test-tools/.github/workflows/public_pr-build-test.yaml@v0
         secrets: inherit
 ```
 
@@ -163,10 +168,147 @@ on:
 
 jobs:
     buildLatest:
-        uses: apify-store/github-actions-source/.github/workflows/push-build-latest.yaml@new_master
+        uses: apify/apify-test-tools/.github/workflows/public_push-build-latest.yaml@v0
         secrets: inherit
 ```
 
+### `claude-review.yaml`
+
+Optional. Reviews a PR against the shared guidelines when you add the trigger label, and again on
+every push while that label is on.
+
+```yaml
+name: Claude review
+
+on:
+    pull_request:
+        types: [labeled, synchronize]
+
+jobs:
+    review:
+        uses: apify/apify-test-tools/.github/workflows/public_review.yaml@v0
+        secrets: inherit
+```
+
+The review instructions live in `.github/review-prompt.md` in this repo and are fetched at run time,
+because a reusable workflow doesn't get its own repo checked out. `prompt-ref` selects which ref to
+fetch them from and defaults to `v0`, so the instructions match the workflow you're calling — point
+it at a branch only to test a prompt change.
+
+### Secrets
+
+Callers pass `secrets: inherit`. The workflows do not turn every inherited secret into job-wide
+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                                                                                                                                                             |
+| `TESTER_APIFY_TOKEN`                                                      | the vitest step only                                                                                                                                                                                                   |
+| `SLACK_TOKEN_TESTS_BOT` / `SLACK_TOKEN_RELEASES_BOT`                      | the reporting and release steps only                                                                                                                                                                                   |
+| `TESTER_APIFY_TOKEN_READ_ONLY`                                            | the Claude investigation step only, as the Apify MCP server's bearer token. Required by `public_platform-tests-claude-investigate-and-fix`. Use a read-only token: it reads the failing run, its log and its storages. |
+
+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
+`${{ toJSON(secrets) }}` as `ALL_SECRETS` and run the command through
+`.github/scripts/run-with-apify-tokens.mjs`, which reads that same config file to decide which
+secrets to pass on:
+
+```yaml
+- name: Build
+  env:
+      ALL_SECRETS: ${{ toJSON(secrets) }}
+  run: |
+      node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
+        npx apify-test-tools build --target-branch ...
+```
+
+The wrapper passes only the tokens the config declares and drops `ALL_SECRETS`, so neither `npx` nor
+anything under `node_modules` sees the blob. Nothing is written to `$GITHUB_ENV`, so the tokens stay
+inside that one command rather than leaking into later steps. Reading the same file
+`apify-test-tools` reads means the two can't drift, and a secret that merely looks like an Actor
+token is not passed just because of its name.
+
+A token the config declares but the repo hasn't set is a warning, not a failure: a repo can carry an
+Actor whose token isn't configured and still build fine as long as that Actor never changes, and
+`apify-test-tools` raises a precise error naming the Actor at the point it actually needs the token.
+
+`scripts-path` comes from the setup action (give the step `id: setup`) and points at this repo's
+`.github/scripts/` directory inside the runner's action checkout, so workflows can run these helpers
+without checking this repo out again. The caller's workspace holds the caller's repo, not this one.
+
+Two tidier-looking alternatives don't work, so don't reach for them:
+
+- **Exporting to `$GITHUB_ENV`** would let the steps call `npx` directly with no wrapper, but
+  `$GITHUB_ENV` applies to every later step in the job. In `pr-build-test` the vitest step runs after
+  the build, so it would inherit Actor tokens it has no use for.
+- **Returning the tokens as a step output** would be scoped correctly, but the runner refuses to set
+  an output whose value contains a registered secret. It logs `Skip output <name> since it may
+contain secret` and leaves the output empty, so anything reading it downstream gets nothing.
+
+The `unitTest` job runs static checks and needs `NPM_TOKEN` only. No job runs `npm ci` with Apify or
+Slack credentials in scope, so a postinstall script in the dependency tree cannot read them.
+
+## Versioning and releases
+
+The workflows and the npm package live in one repo but ship on their own schedules. Two pointers
+decide what a consumer repo actually runs:
+
+| Pointer                             | What it selects                                | Moves when                                               |
+| ----------------------------------- | ---------------------------------------------- | -------------------------------------------------------- |
+| the `@v0` tag in `uses:`            | which workflows run                            | a master push, once the version below is published       |
+| `.github/workflows-package-version` | which `apify-test-tools` the workflows install | a stable release writes it; you may set it ahead of time |
+
+The setup action installs that **exact** version — not a range. A tag is therefore a complete
+statement: these workflows _and_ this library. The stable release writes the file into the same
+commit that bumps `package.json` and `CHANGELOG.md`, so a released commit always names the version
+it published, and rollout latency is unchanged: the release publishes and moves the tag in one run.
+
+Prereleases are excluded. Master pushes publish a `-beta` that consumer repos must never install, so
+the pin only moves on a stable release; betas stay reachable through the lockfile path in the setup
+action, which is how branch testing works.
+
+Nothing is coupled that doesn't need to be:
+
+- **Workflow-only change** — merge it. `v0` moves, it goes live, no release needed.
+- **Package-only change** — merge it, then cut a release when you want it out. The workflows are
+  unchanged, so consumers see nothing until the release lands.
+- **A workflow that calls a new CLI feature** — the one case that can break consumers, and the only
+  one with any ceremony. Put the package change, the workflow change, and the new pin in one PR. On
+  merge the tag is **held**: the CI job reports that the pinned version isn't on npm and leaves `v0`
+  where it is, so consumers keep running the previous workflows. Cut a stable release, and the tag
+  moves on its own. Run **Move major version tag** if you don't want to wait for the next master
+  push.
+
+`v0` moving on every master push means `@v0` is as live as `@master` was — there's no staging step,
+just a gate on the package version. What the tag buys you is a `v1` for breaking workflow changes,
+so repos migrate one at a time instead of all at once, and a way to roll back by pointing the tag at
+an earlier commit. Bump `MAJOR_TAG` in `.github/workflows/_move_major_tag.yaml` to cut the next
+major; the old tag then freezes where it is and keeps working.
+
+Freezing is real, which is the whole reason the version is pinned rather than a floor. A frozen `v0`
+points at a commit whose pinned version never changes, so it keeps installing the library it was
+tested against no matter how far the package moves on. Had the workflows installed `>=<floor>`, a
+frozen `v0` would still resolve to whatever is newest — and since the release that enables `v1` is
+usually the same release that breaks `v0`, the migration window would have been zero.
+
+The tag tracks the **workflows'** contract, not the npm package version. They move independently on
+purpose, so `@v0` is expected to stay `@v0` after the package reaches 1.0 — bump it when a workflow
+breaks its callers, not when the package does. Because `uses:` cannot take an expression, every ref
+into this repo repeats the tag literally; `check-major-tag-refs.mjs` fails the build if `MAJOR_TAG`
+and those refs disagree, which is the mistake that would otherwise ship silently during a bump.
+
+### Testing workflow changes
+
+- Point [testing-repo-for-github-actions](https://github.com/apify-store/testing-repo-for-github-actions)
+  at your branch (`uses: ...@your-branch`). It has real attached Actors and tests. Because the
+  package lives here too, a master push publishes a `beta`, and the lockfile-beta path in the setup
+  action installs that exact version — so one branch tests both halves of a change together.
+- To change the composite action itself, repoint the `uses:` refs inside the reusable workflows at
+  your branch as well, and change them back before merging.
+- Make sure the shell code actually works on your laptop first.
+- After merging, watch the workflow on a real project before moving on.
+
 ## Writing tests
 
 ### Test structure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apify-test-tools",
-  "version": "0.9.1-beta.6",
+  "version": "0.9.1-beta.7",
   "type": "module",
   "description": "TBD",
   "repository": {